La documentation générée doit-elle être stockée dans un référentiel Git?

Lorsque vous utilisez des outils tels que jsdocs , il génère des fichiers HTML statiques et leurs styles dans votre base de code en fonction des commentaires figurant dans votre code.

Ces fichiers doivent-ils être archivés dans le référentiel Git ou doivent-ils être ignorés avec .gitignore?

En l'absence de besoin spécifique, aucun fichier pouvant être construit, recréé, construit ou généré à partir d'outils de construction à l'aide d'autres fichiers archivés dans le contrôle de version ne doit pas être archivé. Lorsque le fichier est requis, il peut être (re) construit à partir de l'autre. sources (et serait normalement comme un aspect du processus de construction).

Donc, ces fichiers doivent être ignorés avec .gitignore.

Ma règle est que lorsque je clone un référentiel et que j'appuie sur un bouton «build», tout est construit au bout d'un moment. Pour ce faire, vous avez le choix entre deux possibilités: soit quelqu'un est responsable de la création de ces documents et de leur mise dans git, soit vous documentez exactement le logiciel dont j'ai besoin sur ma machine de développement, et vous vous assurez que vous appuyez sur le bouton «build». Le bouton construit toute la documentation sur ma machine.

Dans le cas de la documentation générée, où toute modification apportée à un fichier d'en-tête devrait modifier la documentation, il est préférable de le faire sur la machine de chaque développeur, car je souhaite une documentation correcte à tout moment, pas seulement lorsqu'un utilisateur l'a mise à jour. Il existe d'autres situations dans lesquelles générer quelque chose peut prendre beaucoup de temps, être compliqué, nécessiter un logiciel pour lequel vous ne possédez qu'une licence, etc. Dans ce cas, il est préférable de confier à une personne la responsabilité de mettre les choses dans git.

@Curt Simpson: Avoir toutes les exigences logicielles documentées est bien meilleur que ce que j'ai vu dans de nombreux endroits.

Ces fichiers ne doivent pas être archivés car les données pour les générer sont déjà présents. Vous ne voulez pas stocker les données deux fois (DRY).

Si vous avez un système CI, vous pourriez peut-être créer cette documentation et la stocker pour cette construction / publication sur un serveur Web.

L’avantage de les avoir dans certains référentiels (identiques ou différents, de préférence générés automatiquement), c’est que vous pouvez voir toutes les modifications apportées à la documentation. Parfois, ces diffs sont plus faciles à lire que les diffs du code source (en particulier si vous vous souciez uniquement des modifications de spécification, et non de la mise en œuvre).

Mais dans la plupart des cas, les avoir dans le contrôle de code source n'est pas nécessaire, comme l'expliquent les autres réponses.

Ignoré. Vous souhaiterez de toute façon que les utilisateurs du référentiel puissent les reconstruire, ce qui évite d'avoir à s'assurer que les documents sont toujours synchronisés. Il n'y a aucune raison de ne pas regrouper les artefacts construits au même endroit si vous voulez tout avoir au même endroit et ne pas avoir à construire quoi que ce soit. Cependant, les dépôts de source ne sont pas vraiment un bon endroit pour le faire, car la complexité y nuit plus que la plupart des endroits.

Cela dépend de votre processus de déploiement. Cependant, la validation des fichiers générés dans un référentiel est une exception et doit être évitée, si possible. Si vous pouvez répondre aux deux questions suivantes avec Oui , l’archivage de vos documents peut être une option valide:

• Les documents sont-ils une exigence pour la production?
• Votre système de déploiement manque-t-il des outils nécessaires pour construire les documents?

Si ces conditions sont remplies, vous déployez probablement avec un système hérité ou un système avec des contraintes de sécurité particulières. Au lieu de cela, vous pouvez valider les fichiers générés dans une branche de publication et maintenir la branche principale propre.

Ça dépend. Si ces docs:

• Doit faire partie du référentiel, comme le readme.md, alors il est préférable de les conserver dans le dépôt git. Parce qu'il peut être difficile de gérer ces situations de manière automatisée.

• Si vous ne disposez pas d'un moyen automatisé de les construire et de les mettre à jour, comme un système CI, et qu'il est destiné à être vu par le grand public, il est préférable de les conserver dans le référentiel git.

• Il faut BEAUCOUP de temps pour les construire, alors il est légitime de les conserver.

• Sont destinés à être vus pour le grand public (comme le manuel d'utilisation), et cela prend un temps considérable à construire, alors que vos documents précédents deviennent inaccessibles (hors ligne), il est alors justifiable de les conserver dans le dépôt git.

• Sont destinés à être vus par le grand public et doivent montrer un historique de ses changements / évolutions, il pourrait être plus facile de garder les versions précédentes du document engagées et de construire / engager la nouvelle version liée à la précédente. Justifiable.

• A une raison acceptée spécifique pour que toute l'équipe soit engagée, il est alors justifiable de les garder dans le dépôt Git. (Nous ne connaissons pas votre contexte, votre équipe et vous le savez)

Dans tout autre scénario, il devrait être ignoré en toute sécurité.

Toutefois, s’il est justifié de les conserver dans le dépôt git, cela pourrait indiquer un autre problème plus important auquel votre équipe est confrontée. (Ne pas avoir un système de CI ou des problèmes de performance similaires, horribles, faire face aux temps morts pendant la construction, etc.)

En tant que principe de contrôle de version, seuls les "objets primaires" doivent être stockés dans un référentiel, pas les "objets dérivés".

Il existe des exceptions à la règle: à savoir, lorsque des utilisateurs du référentiel ont besoin des objets dérivés et que l'on peut raisonnablement s'attendre à ce qu'ils ne disposent pas des outils nécessaires pour les générer. D'autres considérations entrent en ligne de compte, comme est la quantité de matériau difficile à manier? (Serait-il préférable que le projet demande à tous les utilisateurs de disposer des outils?)

Un exemple extrême de ceci est un projet qui implémente un langage de programmation rare dont le compilateur est écrit dans ce langage lui-même (des exemples bien connus incluent Ocaml ou Haskell) Si seul le code source du compilateur est dans le référentiel, personne ne peut le construire. ils ne disposent pas d'une version compilée du compilateur qu'ils peuvent exécuter sur la machine virtuelle afin de pouvoir compiler le code source de ce compilateur. De plus, les dernières fonctionnalités du langage sont immédiatement utilisées dans le source du compilateur lui-même, de sorte qu'il est toujours nécessaire de s'approcher de la dernière version du compilateur pour le compiler: un exécutable de compilateur vieux d'un mois obtenu séparément ne compilera pas le code actuel utilise des fonctionnalités de langage qui n'existaient pas il y a un mois. Dans cette situation, la version compilée du compilateur doit presque certainement être archivée dans le référentiel et mise à jour.