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

68

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

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

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

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

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

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

EmpireJones
источник
Ах, хорошо ... спасибо за разъяснения. Я не понимаю, почему это будет проблемой, но у меня нет личного опыта работы с GIT (просто теоретическое понимание), поэтому я позволю кому-то с более непосредственным опытом ответить на этот вопрос.
Хлипкий
1
Я не совсем понимаю, как это по теме. Вы говорите о документации программного обеспечения и фиксации с DVCS
Тим Пост
Вероятно, зависит от документации и ваших потребностей. Вам нужны различия, и это в формате, который может с этим справиться? Если Git предоставляет необходимые услуги, конечно. Ударяет наличие отдельной системы управления документами ...
Rig
Если ваша документация в виде простого текста - хорошо. Если это двоичный формат, вам, по сути, нужна система контроля версий, которая понимает двоичный формат - это блокировка поставщика в чистом виде.

Ответы:

53

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

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

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

Flimzy
источник
11
Если вы магазин Microsoft, TortoiseSVN поддерживает построчную разность MS Office.
Фил
2
Отказ от двоичных форматов документов сделает мир лучше. o учитывая, что документы имеют открытый текст, с DVCS также не должно быть никаких реальных проблем.
Кай Инкинен
О, и впервые я услышал о TortoiseSVN и файлах документации, так что +1 за это. Интересно, будет ли это в конечном итоге на черепахе [AnyDVCS] в будущем.
Кай Инкинен
@Phil: Как TortoiseSVN достигает этого? Интегрирован ли doc-diff viewer с клиентом SVN или его можно использовать независимо?
Хлипкий
1
Отличный вариант - использовать Pandoc, чтобы большая часть документации была в Markdown, но важнейшие биты все еще могут использовать TeX. Поскольку он компилирует Markdown в LaTeX, результаты выглядят одинаково. Однако это также позволит вам экспортировать его в другие форматы и упростит чтение исходного кода.
Тихон Джелвис
22

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

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

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

cstamas
источник
Я согласен, хотя можно хранить нетекстовую документацию, git будет намного лучше, если вы сохраните текст вместо этого.
Говорили о драйвере различий,
Хотя Word переместил их формат из двоичного в XML.
Cledoux
3
@ karategeek6 Формат Word в формате XML недоступен для чтения человеком. И одна строка текста не соответствует одной строке XML в Word, даже в приближении. Так что это может быть двоичным.
Вы можете указать Word сохранить ваш вывод в несжатом XML. Выберите Save As, затем выберите Word XML Document (*.xml)вместо значения по умолчанию Word Document (*.docx). XML довольно сложный, так что это не гарантирует, что изменения будут легко читаемыми, но, по крайней мере, они не будут двоичными.
Kyralessa
> Но вывод diff не будет иметь смысла. В случае различий, мы могли бы открыть 2 ревизии документа бок о бок и сравнить на наших глазах :)
Люк
14

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


источник
6
Только если документация в текстовом виде. Двоичные двоичные объекты не в полной мере получают выгоду от контроля версий.
2
@ ThorbjørnRavnAndersen: Несмотря на это, если у вас нет системы управления версиями для двоичных файлов, вероятно, лучше хранить даже двоичные файлы в Git, а не самостоятельно.
Тихон Джелвис
@TikhonJelvis Я не задавался вопросом, будет ли хорошей идеей помещать двоичные файлы в git - если они являются оригинальными артефактами, это так. Попробуйте, однако, запустить «git diff» для документов Word.
@ user1249: вы можете «экспортировать» 2 ревизию на рабочий стол, скажем, my_docs_rev15.docx и my_docs_rev14.docx, а затем открыть ее рядом и сравнить своими глазами и мозгом, это не так сложно :)
Люк
14

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

Ma99uS
источник
3
Да, аспект «в том же месте» является одной из ключевых частей этого вопроса!
Одно и то же местоположение хорошо, если вы можете им управлять, потому что оно избегает необходимости иметь племенные знания (знание, где искать) или необходимость искать, где находится материал.
quick_now
Возможно, им не нужен доступ к коду, но им не должно быть больно иметь такой доступ. Им не нужно смотреть на это. Как правило, секреты не должны быть в управлении версиями.
BDSL
9

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

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

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

confiq
источник
2
Разве вы не имеете в виду Mediawiki, движок вики, который использует Википедия?
@Martijn, я бы так предположил
Teo Klestrup Röijezon
@Martijn: Да, отредактировано
confiq
Я предпочел бы придерживаться вики, а не отправлять много файлов, которые не являются курсом для SCM, но это больше связано с личными предпочтениями. С этим можно сделать гораздо больше. Мне особенно нравится Foswiki и их шаблон на основе веб-сайтов / проектов. Рад, что кто-то указал на решение использовать вики из-за проблем :) +1.
Oeufcoque Penteano
9
  • Наличие в репозитории не только исходного кода - это очень хорошая вещь.

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

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

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

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

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


* Это не совсем точно, потому что есть способы указать части файла для фиксации ( вот один пример ).

Тайлер Уэйн
источник
4

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

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

Элке Блок
источник
Различные ветки с совершенно разной структурой каталогов имеют очень неприятный запах кода для меня. Я бы оставил все это в одном репо, чтобы участникам было легче добавлять смесь кода и документации. На самом деле, грамотное программирование (Google, что!) Требует этого.
tbc0
При распространении пакетов я неравнодушен к стилю .deb, который позволяет загружать исполняемые файлы на все серверы, в то время как в моей коробке разработки также есть пакеты документации.
tbc0
1

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

Майкл Браун
источник
-1

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

tbc0
источник