Должен ли Git использоваться для документации и управления проектами? Должен ли код находиться в отдельном репозитории?

Я запускаю Git-репозиторий для группового проекта. Имеет ли смысл хранить документы в том же репозитории Git, что и код - кажется, что это противоречит природе потока изменений git.

Вот краткое изложение моих вопросов:

• Будет ли стиль редакции Git сбивать с толку, если и код, и документы проверяются в одном и том же хранилище ? Опыт с этим?

• Git хорошо подходит для контроля версий документации?

• Я НЕ спрашиваю, должна ли система контроля версий вообще или не должна использоваться для документации - она ​​должна.

Спасибо за отзыв до сих пор!

Мы постоянно храним документацию в SVN. На самом деле, все руководство пользователя написано на LaTeX и хранится в SVN. Мы выбрали LaTeX специально, потому что это текстовый язык, и его легко показывать построчно.

Мы также храним некоторые нетекстовые отформатированные файлы, такие как .doc-файлы Microsoft Office, электронные таблицы, ZIP-файлы и т. Д., Когда это необходимо ... но некоторые преимущества RCS теряются, когда вы не видите инкрементный файл. дифференциалы.

Главное - убедиться, что ваша документация хорошо организована, чтобы люди могли находить (и обновлять) документацию (и источник), когда им это нужно.

Ну, это зависит от того, какой формат вы используете для документации. Если это что-то текстовое, то все хорошо.

Git также может хранить двоичный контент, и вы можете отслеживать ревизии, но вывод diff не будет иметь смысла.

Также можно хранить документацию в самом коде, например, в perldoc pod, для этого в java также есть некоторый формат / аннотации.

Я не могу представить, почему вы думаете, что может быть проблема с использованием git или любой другой системы контроля версий для документации. Как и исходный код, документация должна иметь полную историю и возможность вернуться к более ранней версии, если в этом возникнет необходимость. Система контроля версий идеально подходит для этого.

Понятно, что использование какой-либо системы контроля версий для хранения документов - это не просто мозг. Более интересная часть вопроса - хорошая ли идея хранить документы в одном и том же месте в качестве исходного кода? Возможная проблема здесь заключается в том, что в этом случае может быть трудно установить разные права доступа для кода и документации. И во многих бизнес-случаях людям потребуется доступ к документам, но не к исходному коду, например, к отделам маркетинга или BA.

В компании, в которой я работаю, мы помещаем документацию в SVN. Однако, после нескольких конфликтов и необходимости делиться ими, мы решили перенести это в Mediawiki.

Сначала это был trac, после чего он перешел в Mediawiki, потому что его было проще использовать ...

Основной проблемой с SVN было разделение, потому что у нас была система авторизации для SVN.

• Наличие в репозитории не только исходного кода - это очень хорошая вещь.

  Он группирует все ваши ресурсы вместе и превращает проект в целостную централизованную сущность, а не в разрозненную коллекцию файлов. Авторы / сотрудники знают, где найти все, вместо того, чтобы отправлять «Где я могу изменить документацию для функции x?» электронные письма.

  Вы будете хотеть держать вещи организованными. Есть система для отделения srcот imagesот docs. Вы всегда можете добавить .gitignoreв каталог, чтобы сохранить хранилище и историю в чистоте. Поскольку коммиты Git основаны на файлах, * вы можете отделить изменения источника от изменений документации настолько сильно, насколько вам угодно.

• Как уже говорили другие, Git отлично подходит для управления версиями документации, если он основан на тексте.

• Я полностью согласен; документация должна быть версионирована вместе с кодом.

Мой авторитет прибывает из того, что я - пользователь GitHub и участвую в одном проекте и исследую много других. По моему опыту, полный, унифицированный проект легко отличить от наполовину отсутствующего. Я стараюсь по возможности содержать все мои проекты в отдельных каталогах.

Я пришел сюда с похожим вопросом. Мы пришли из SVN-среды, где, по сути, нетрудно хранить все материалы, связанные с проектом, в одном хранилище. Из-за особенностей SVN вы можете легко проверить части репозитория, поэтому если вам нужен только исходный код (например, развертывание веб-сайта), это не проблема.

С Git все по-другому. Оформление заказа всегда находится на корневом уровне, поэтому, если вы хотите поместить все в один и тот же репозиторий, у вас всегда будет одинаковая структура каталогов. Один подход, с которым я столкнулся, состоит в том, чтобы поместить все в отдельные ветви, т.е. у вас есть ветки кода (которые обычно были бы вашими обычными ветвями master, development и т. Д.) И ветка doc, которая имеет свою собственную, отдельную структуру каталогов. Я еще не уверен, что это лучшая идея, но это предложение, которое обходит проблему, которая, как мне кажется, лежит в основе вашего вопроса.

Я использую вики для внутренних документов ... получить ревизию ПЛЮС выдающийся доступ / легкое редактирование. Когда документация не синхронизирована, обновите ее прямо здесь и сейчас. Для документации конечного пользователя рассмотрим профессиональный инструмент, такой как Madcap Flare. Они используют диалект XML для совместного использования, составления и преобразования документации.

В коде мысли обычно разделяются построчно. Я склонен писать документацию с мягкими переносами строк. Когда я фиксирую эти файлы, строки составляют целый абзац. Это не очень полезно читать git diff. Это проблема, которую я пытался решить, когда гуглил и нашел эту страницу. Спасибо Арне Хартцер за то, что познакомил меня с git diff --word-diff. Тебе может понравиться git diff --color-wordsеще лучше.