Чи слід зберігати створену документацію у сховищі Git?

Коли ви використовуєте такі інструменти, як jsdocs , він генерує статичні файли HTML та його стилі у вашій кодовій базі на основі коментарів у вашому коді.

Чи слід перевіряти ці файли у сховищі Git чи їх слід ігнорувати .gitignore?

Якщо немає будь-якої конкретної потреби, будь-який файл, який можна створити, відтворити, сконструювати або генерувати з інструментів збирання за допомогою інших файлів, перевірених на контроль версій, не слід перевіряти. Коли файл потрібен, він може бути (пере) побудований з іншого джерела (і зазвичай це є деяким аспектом процесу збирання).

Тому ці файли слід ігнорувати за допомогою .gitignore.

Моє правило: коли я клоную сховище і натискаю кнопку «побудувати», то через деякий час все будується. Щоб досягти цього для вашої згенерованої документації, у вас є два варіанти: або хтось несе відповідальність за створення цих документів і введення їх в git, або ви документуєте саме те, яке програмне забезпечення мені потрібно на моїй розроблювальній машині, і ви переконайтесь, що натискаєте кнопку "build" кнопка збирає всю документацію на моїй машині.

У випадку згенерованої документації, коли будь-яка зміна, яку я вношу у файл заголовка, повинна змінювати документацію, робити це краще на машині кожного розробника, тому що я хочу правильну документацію весь час, а не лише коли хтось її оновлював. Існують й інші ситуації, коли генерування чогось може зайняти багато часу, складна, вимагає програмного забезпечення, на яке ви маєте лише одну ліцензію і т. Д. У такому випадку краще дати відповідальності людині за те, щоб передати речі в git.

@Curt Сімпсон: Маючи всі вимоги до програмного забезпечення документованого це набагато краще , ніж я бачив у багатьох місцях.

Ці файли не повинні бути зареєстровані, оскільки дані для їх генерування вже є. Ви не хочете двічі зберігати дані (DRY).

Якщо у вас є система CI, ви, можливо, зможете зробити так, щоб створити документи і зберегти їх для створення / публікації на веб-сервері.

Однією з переваг наявності їх у якомусь сховищі (або тому самому, або іншому, бажано автоматично генерованому) є те, що потім ви можете побачити всі зміни в документації. Іноді ці диффлакти читаються легше, ніж відмінності до вихідного коду (зокрема, якщо ви дбаєте лише про зміни специфікацій, а не про реалізацію).

Але в більшості випадків наявність їх у контролі джерел не потрібна, як пояснено в інших відповідях.

Проігноровано. Ви хочете, щоб користувачі репо змогли відновити їх у будь-якому випадку, і це знімає складність бути впевненим, що документи завжди синхронізовані. Немає причин не збирати вбудовані артефакти в одному місці, якщо ви хочете мати все в одному місці і нічого не потрібно будувати. Однак джерельні репортажі насправді не гарне місце для цього, однак, оскільки їх складність шкодить більше, ніж більшість місць.

Це залежить від вашого процесу розгортання. Але створення згенерованих файлів у сховище є винятком і його слід уникати, якщо це можливо. Якщо ви можете відповісти на обидва наступні питання за допомогою " Так" , перевірка в документах може бути правильним варіантом:

• Чи є документація вимогою до виробництва?
• Чи не має у вашій системі розгортання необхідних інструментів для створення документів?

Якщо ці умови справжні, ви, ймовірно, розгортаєтесь зі застарілою системою або системою зі спеціальними обмеженнями безпеки. Як альтернативу, ви можете зафіксувати згенеровані файли у гілці випуску та зберегти чисту гілку чистим.

Це залежить. Якщо ці документи:

• Потрібно бути частиною сховища, як-от readme.md, тоді бажано зберігати їх у git repo. Тому що впоратися з цими ситуаціями на автоматизованому шляху може бути складним.

• Якщо у вас немає автоматизованого способу їх створення та оновлення, як система CI, і він призначений для перегляду для широкої аудиторії, тоді вважається за краще зберігати їх у git repo.

• Знадобиться багато часу для їх побудови, тоді виправдано зберегти їх.

• Вони призначені для перегляду для широкої аудиторії (як-от посібник користувача), і це потребує значного часу, коли ваші попередні документи стають недоступними (в режимі офлайн), тоді виправдано зберігати їх у git repo.

• Якщо вони призначені для широкої аудиторії та мають показати історію її змін / еволюції, це може бути простіше зберегти попередні версії doc, скоєними, і створити / здійснити нову, пов'язану з попередньою. Обґрунтованість

• Є конкретна прийнята причина для всіх команд, які повинні бути прийняті на посаду, то виправдано зберігати їх у репо-релізі. (Ми не знаємо вашого контексту, ви та ваша команда)

У будь-якому іншому сценарії це слід сміливо ігнорувати.

Однак, якщо виправдати їх утримувати в git repo, це може бути ознакою ще одного більшого питання, з яким стикається ваша команда. (Не має системи CI або подібних, жахливих проблем з роботою, зіткнувся з простоєм під час будівництва тощо)

Як принцип контролю версій, у сховищі повинні зберігатися лише "первинні об'єкти", а не "похідні об'єкти".

Існують винятки з правила: а саме, коли є споживачі сховища, які потребують похідних об'єктів, і обґрунтовано очікується, що вони не матимуть необхідних інструментів для їх створення. Інші міркування важать, як, наприклад, кількість матеріалу, який не є громіздким? (Було б краще, щоб проект просто дозволив усім користувачам мати інструменти?)

Крайній приклад цього - проект, який реалізує рідкісну мову програмування, компілятор написаний цією мовою (добре відомі приклади включають Ocaml або Haskell). Якщо в репозиторії є лише вихідний код компілятора, ніхто не може створити його; у них немає компільованої версії компілятора, яку вони можуть працювати на віртуальній машині, щоб вони могли скомпілювати вихідний код цього компілятора. Більше того, останні функції мови негайно використовуються в самому джерелі компілятора, так що для його побудови завжди потрібна близька до останньої версії компілятора: місячний старий виконаний компілятор, отриманий окремо, не буде компілювати поточний код, оскільки код використовує мовні функції, які не існували місяць тому. У цій ситуації складену версію компілятора майже напевно потрібно перевірити в сховищі та оновлювати.