Когда вы используете такие инструменты, как jsdocs , он генерирует статические HTML-файлы и их стили в вашей кодовой базе на основе комментариев в вашем коде.
Должны ли эти файлы быть добавлены в репозиторий Git или их следует игнорировать с помощью .gitignore?
git
documentation
вывоз мусора
источник
источник
Ответы:
При отсутствии какой-либо конкретной необходимости, любой файл, который может быть собран, воссоздан, сконструирован или сгенерирован из инструментов сборки с использованием других файлов, отмеченных в управлении версиями, не должен быть возвращен. Когда файл необходим, он может быть (повторно) собран из другого исходники (и, как правило, будут как некоторые аспекты процесса сборки).
Поэтому эти файлы следует игнорировать с помощью .gitignore.
источник
Мое правило таково: когда я клонирую репозиторий и нажимаю кнопку «сборки», через некоторое время все строится. Чтобы добиться этого для сгенерированной документации, у вас есть два варианта: либо кто-то отвечает за создание этих документов и их размещение в git, либо вы документируете, какое именно программное обеспечение мне нужно на моей машине для разработки, и вы нажимаете «build» Кнопка строит всю документацию на моей машине.
В случае сгенерированной документации, где любое отдельное изменение, которое я делаю в заголовочном файле, должно изменить документацию, делать это на компьютере каждого разработчика лучше, потому что я хочу исправлять документацию все время, а не только когда кто-то ее обновил. Существуют и другие ситуации, когда создание чего-либо может занять много времени, усложниться, потребовать программного обеспечения, для которого у вас есть только одна лицензия, и т. Д. В этом случае лучше поручить одному человеку ответственность за внесение изменений в git.
@ Курт Симпсон: Документирование всех требований к программному обеспечению намного лучше, чем я видел во многих местах.
источник
./Testи получить сборку или получить хорошую информацию о том, что ему нужно сделать, чтобы получить сборку.Эти файлы не должны быть возвращены, потому что данные для их создания уже присутствуют. Вы не хотите хранить данные дважды (СУХОЙ).
Если у вас есть система CI, вы можете создать документацию и сохранить ее для этой сборки / опубликовать ее на веб-сервере.
источник
Одно из преимуществ наличия их в каком-либо репозитории (либо в том же, либо в другом, предпочтительно автоматически сгенерированном) состоит в том, что тогда вы можете видеть все изменения в документации. Иногда эти различия легче читать, чем различия в исходном коде (особенно если вы заботитесь только об изменениях спецификации, а не о реализации).
Но в большинстве случаев их не нужно контролировать в исходном коде, как объяснили другие ответы.
источник
Игнорируется. Вы захотите, чтобы пользователи репо могли их перестроить в любом случае, и это устраняет сложность уверенности в том, что документы всегда синхронизированы. Нет причин не собирать собранные артефакты в одном месте, если вы хотите, чтобы все было в одном месте и не нужно ничего строить. Однако исходные репозитории на самом деле не являются хорошим местом для этого, хотя сложность там вредит больше, чем в большинстве мест.
источник
Это зависит от вашего процесса развертывания. Но фиксация сгенерированных файлов в хранилище является исключением, и его следует избегать, если это возможно. Если вы можете ответить на оба следующих вопроса с помощью Да , проверка ваших документов может быть допустимым вариантом:
Если эти условия выполняются, возможно, вы развертываете с устаревшей системой или системой с особыми ограничениями безопасности. В качестве альтернативы вы можете зафиксировать сгенерированные файлы в ветке релиза и поддерживать чистоту главной ветки.
источник
По-разному. Если эти документы:
Должен быть частью репозитория, как
readme.md, то желательно, чтобы они оставались в репозитории git. Потому что это может быть сложно обрабатывать такие ситуации в автоматическом режиме.Если у вас нет автоматизированного способа их создания и обновления, такого как система CI, и он предназначен для просмотра широкой аудиторией, тогда предпочтительнее хранить их в git-репо.
Занимает много времени, чтобы построить их, а затем оправданно их сохранить.
Предназначены для просмотра широкой аудиторией (например, руководством пользователя), и на их сборку уходит значительное время, в то время как ваши предыдущие документы становятся недоступными (в автономном режиме), а затем их можно хранить в репозитории git.
Предназначены для просмотра широкой аудиторией и должны показывать историю ее изменений / эволюции, может быть проще сохранить прежние версии документа и создать / зафиксировать новую, связанную с предыдущей. Необходимая.
Имеет конкретную общепринятую причину, по которой все команды должны быть приняты, и тогда оправданно держать их в git-репо. (Мы не знаем ваш контекст, вы и ваша команда знаете)
В любом другом сценарии его следует смело игнорировать.
Однако, если оправданно держать их в git-репо, это может быть признаком еще одной более серьезной проблемы, с которой сталкивается ваша команда. (Отсутствие системы CI или аналогичной системы, ужасные проблемы с производительностью, время простоя при сборке и т. Д.)
источник
В качестве принципа контроля версий в репозитории должны храниться только «первичные объекты», а не «производные объекты».
Из этого правила есть исключения: а именно, когда есть пользователи репозитория, которым требуются производные объекты, и разумно ожидать, что у них не будет необходимых инструментов для их генерации. Другие соображения весят, как количество материала громоздко? (Будет ли лучше, если бы у всех пользователей были инструменты?)
Экстремальным примером этого является проект, который реализует редкий язык программирования, компилятор которого написан на этом языке (хорошо известные примеры включают Ocaml или Haskell). Если в репозитории находится только исходный код компилятора, никто не сможет его собрать; у них нет скомпилированной версии компилятора, которую они могли бы запустить на виртуальной машине, чтобы они могли скомпилировать исходный код этого компилятора. Более того, последние возможности языка сразу же используются в самом исходном коде компилятора, так что для его сборки всегда требуется близкий к последней версии компилятор: исполняемый файл компилятора месяца, полученный отдельно, не будет компилировать текущий код, потому что код использует языковые функции, которых не было месяц назад. В этой ситуации скомпилированная версия компилятора почти наверняка должна быть проверена в хранилище и обновлена.
источник