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 ses styles dans votre base de code en fonction des commentaires de 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, tout fichier pouvant être généré, recréé, construit ou généré à partir d'outils de génération à l'aide d'autres fichiers archivés dans le contrôle de version ne doit pas être archivé. Lorsque le fichier est nécessaire, il peut être (re) généré à partir de l'autre sources (et serait normalement comme un aspect du processus de construction).
Ces fichiers doivent donc être ignorés avec .gitignore.
Ma règle est que lorsque je clone un référentiel et appuie sur un bouton "build", puis, après un certain temps, tout est construit. Pour y parvenir pour votre documentation générée, vous avez deux choix: soit quelqu'un est responsable de la création de ces documents et de les mettre dans git, soit vous documentez exactement de quel logiciel j'ai besoin sur ma machine de développement, et vous vous assurez qu'en appuyant sur le bouton "build" Le bouton crée toute la documentation sur ma machine.
Dans le cas de la documentation générée, où toute modification unique que j'apporte à 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 veux une documentation correcte tout le temps, pas seulement lorsque quelqu'un l'a mise à jour. Il y a d'autres situations où générer quelque chose peut être long, compliqué, nécessiter un logiciel pour lequel vous n'avez qu'une seule licence, etc. Dans ce cas, donner à une personne la responsabilité de mettre les choses en git est mieux.
@Curt Simpson: Avoir toutes les exigences logicielles documenté est beaucoup mieux 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ésentes. Vous ne souhaitez pas stocker deux fois les données (SEC).
Si vous avez un système CI, vous pourriez peut-être faire construire les documents et les stocker pour cette génération/le publier sur un serveur Web.
Un avantage de les avoir dans un référentiel (le même ou un autre, de préférence généré automatiquement) est que vous pouvez alors voir toutes les modifications apportées à la documentation. Parfois, ces différences sont plus faciles à lire que les différences avec le code source (en particulier si vous ne vous souciez que des modifications de spécifications, pas de l'implémentation).
Mais dans la plupart des cas, les avoir en contrôle de source n'est pas nécessaire, comme l'ont expliqué les autres réponses.
Ignoré. Vous voudrez que les utilisateurs du dépôt soient en mesure de les reconstruire de toute façon, et cela élimine la complexité d'être sûr que les documents sont toujours synchronisés. Il n'y a aucune raison de ne pas regrouper les artefacts construits en un seul endroit si vous voulez tout avoir en un seul endroit et ne pas avoir à construire quoi que ce soit. Cependant, les dépôts source ne sont pas vraiment un bon endroit pour le faire, car la complexité fait plus mal que la plupart des endroits.
Cela dépend de votre processus de déploiement. Mais 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 de production?
- Votre système de déploiement ne dispose-t-il pas des outils nécessaires pour créer 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é spéciales. Comme alternative, vous pouvez valider les fichiers générés dans une branche de publication et garder la branche principale propre.
Ça dépend. Si ces documents:
Doit faire partie du référentiel, comme le
readme.md, 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 créer 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.
Prend BEAUCOUP de temps pour les construire, puis il est justifié de les conserver.
Ils sont destinés à être vus par le grand public (comme le manuel de l'utilisateur), et leur construction prend beaucoup de temps, tandis que vos documents précédents deviennent inaccessibles (hors ligne), puis il est justifié de les conserver dans le dépôt git.
Sont destinés à être vus pour le grand public et doivent montrer un historique de ses changements/évolution, il pourrait être plus facile de garder les versions de document précédentes engagées et de construire/valider la nouvelle liée à la précédente. Justifiable.
A une raison spécifique acceptée pour que toute l'équipe soit engagée, alors il est justifié de les garder dans le dépôt git. (Nous ne connaissons pas votre contexte, vous et votre équipe le savez)
Dans tout autre scénario, il doit être ignoré en toute sécurité.
Cependant, s'il est justifié de les conserver dans le référentiel git, cela pourrait être un signe d'un autre problème plus important auquel votre équipe est confrontée. (Ne pas avoir de système CI ou de problèmes de performances horribles similaires, faire face à des temps d'arrêt lors de la construction, etc.)
En tant que principe de contrôle de version, seuls les "objets principaux" 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 sont raisonnablement censés ne pas disposer des outils nécessaires pour les générer. D'autres considérations entrent en ligne de compte, comme la quantité de matière lourde à manier? (Serait-il préférable pour le projet que tous les utilisateurs disposent 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 se trouve dans le référentiel, personne ne peut le construire; ils n'ont pas de version compilée du compilateur qu'ils peuvent exécuter sur la machine virtuelle, afin qu'ils puissent compiler le code source de ce compilateur. De plus, les dernières fonctionnalités du langage sont immédiatement utilisées dans la source du compilateur lui-même, de sorte que près de la dernière version du compilateur est toujours nécessaire pour le construire: un exécutable de compilateur d'un mois obtenu séparément ne compilera pas le code actuel car le code 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 maintenue à jour.