Git doit-il être utilisé pour la documentation et la gestion de projet? Le code doit-il être dans un référentiel séparé?

68

Je démarre un référentiel Git pour un projet de groupe. Est-il judicieux de stocker des documents dans le même référentiel Git en tant que code - il semble que cela soit en conflit avec la nature du flux de révision de Git .

Voici un résumé de ma (mes) question (s):

Le style de révision Git va-t-il créer de la confusion si le code et les documents sont archivés dans le même référentiel ? Des expériences avec ça?
Git convient-il au contrôle de révision de la documentation?
Je ne demande pas si un système de contrôle de révision en général devrait ou ne devrait pas être utilisé pour la documentation - il le devrait.

Merci pour les commentaires jusqu'à présent!

git version-control project-management

— EmpireJones
source

Ah, d'accord ... merci pour la clarification. Je ne vois pas pourquoi cela poserait un problème, mais je n'ai aucune expérience personnelle de GIT (juste une compréhension théorique), je vais donc laisser une personne ayant une expérience plus directe répondre à cette question.

— Flimzy

1

Je ne vois pas très bien comment c'est sur le sujet. Vous parlez de documentation de logiciel et vous engagez avec un DVCS

— Tim Post

Cela dépend probablement de la documentation et de vos besoins. Avez-vous besoin de diffs et est-ce dans un format qui peut le gérer? Si git donne les services requis bien sûr. Beats ayant un système de gestion de documents séparé ...

— Rig

Si votre documentation est en texte brut, très bien. S'il s'agit d'un format binaire, vous avez essentiellement besoin d'un système de contrôle de version comprenant le format binaire - il s'agit du verrouillage du fournisseur dans sa forme la plus pure.

related: Quelle partie de votre projet devrait être dans le contrôle de code source?

— Gnat

53

Nous stockons la documentation dans SVN tout le temps. En fait, tout notre manuel d’utilisation est écrit en LaTeX et stocké en SVN. Nous avons choisi LaTeX spécifiquement parce que c'est un langage textuel, et qu'il est facile d'afficher des différences ligne par ligne.

Nous stockons également certains fichiers non au format texte, tels que les fichiers .doc, tableurs, fichiers .zip, etc., de Microsoft Office, mais certains avantages d’un RCS sont perdus lorsque vous ne pouvez pas voir la valeur incrémentielle. diffs.

La clé est vraiment de vous assurer que votre documentation est bien organisée, afin que les gens puissent trouver (et mettre à jour) la documentation (et la source) quand ils en ont besoin.

— Flimzy
source

11

Si vous êtes un magasin Microsoft, TortoiseSVN prend en charge les diffs ligne par ligne MS Office.

— Phil

2

Abandonner les formats de doc binaires ferait du monde un meilleur endroit. o Étant donné que les documents sont en texte brut, il ne devrait pas y avoir de réel problème avec un DVCS.

— Kai Inkinen

Oh, et la première fois que j'ai entendu parler de TortoiseSVN et des fichiers doc, donc +1 pour cela. Je me demande si cela finira sur Tortoise [AnyDVCS] à tout moment dans le futur.

— Kai Inkinen

@Phil: Comment TortoiseSVN accomplit-il cela? Le visualiseur doc-diff est-il intégré au client SVN ou peut-il être utilisé indépendamment?

— Flimzy

1

Une option intéressante consisterait à utiliser Pandoc de sorte que la majeure partie de votre documentation soit dans Markdown, mais les éléments cruciaux peuvent toujours utiliser TeX. Comme il compile le Markdown en LaTeX, les résultats sont identiques. Cependant, cela vous permettrait également de l'exporter dans différents formats et faciliterait la lecture de la source.

— Tikhon Jelvis

22

Cela dépend de quel format utilisez-vous pour la documentation. Si c'est quelque chose à base de texte c'est tout bon.

Git peut également stocker du contenu binaire et vous pouvez suivre les révisions, mais la sortie de diff n'aura aucun sens.

Il est également possible de stocker la documentation dans le code lui-même, comme perldoc pod. Java a également un format / annotation pour cela.

— cstamas
source

Je suis d’accord, bien qu’il soit possible de stocker de la documentation non textuelle, git fera beaucoup mieux si vous stockez du texte à la place. Il a été question d'un pilote de diff capable de différencier les documents Word (ou similaires), mais je ne sais pas s'il a été implémenté ou non

— Sverre Rabbelier le

Je pense que Word a déplacé leur format de binaire à XML.

— Cledoux

3

@ karategeek6 Le format 'XML' de Word n'est pas lisible par l'homme. Et une ligne de texte ne correspond pas à une ligne du code XML de Word, même approximativement. Donc, cela pourrait aussi bien être binaire.

Vous pouvez demander à Word de sauvegarder votre sortie au format XML non compressé. Choisissez Save As, puis sélectionnez Word XML Document (*.xml)au lieu de la valeur par défaut Word Document (*.docx). Le XML est assez complexe, il n’est donc pas garanti que les modifications seront facilement lisibles, mais au moins ce ne sera pas binaire.

— Kyralessa

> mais la sortie diff n'aura aucun sens. En cas de diff, nous pourrions ouvrir 2 révisions d'un document côte à côte et comparer par nos yeux :)

— Luke

14

Je ne peux pas imaginer pourquoi vous pensez qu'il pourrait y avoir un problème d'utilisation de git, ou de tout autre système de contrôle de version, pour la documentation. Tout comme le code source, la documentation devrait avoir un historique complet et la possibilité de revenir à une version antérieure si cela devenait nécessaire. Un système de contrôle de version est parfait pour cela.

6

Seulement si la documentation est sous forme de texte. Les blobs binaires ne bénéficient pas pleinement du contrôle de version.

2

@ ThorbjørnRavnAndersen: Même dans ce cas, à moins que vous n'ayez un système de gestion de versions binaire spécifique, il est probablement préférable de conserver même les fichiers binaires dans Git plutôt que par eux-mêmes.

— Tikhon Jelvis

@TikhonJelvis Je ne me suis pas demandé si c'était une bonne idée de mettre des fichiers binaires dans git - si ce sont les artefacts originaux, c'est bien le cas. Essayez toutefois d’exécuter "git diff" sur des documents Word.

@ user1249: vous pouvez "exporter" 2 révisions sur le bureau, dites my_docs_rev15.docx et my_docs_rev14.docx, puis ouvrez-les côte à côte et comparez-les par vos yeux et votre cerveau, ce n'est pas si difficile :)

— Luke

14

Il est clair que l'utilisation d'un système de contrôle de version pour stocker des documents n'est pas un enthousiasme. La partie la plus intéressante de la question est de savoir s'il est judicieux de stocker des documents à l'emplacement SAME en tant que code source? Le problème possible ici est qu'il peut être difficile de définir des privilèges d'accès différents pour le code et la documentation dans ce cas. Et dans de nombreux cas, les utilisateurs auront besoin d'accéder à la documentation mais pas au code source, comme le marketing ou les départements de BA.

— Ma99uS
source

3

Oui, l'aspect "même emplacement" est l'un des éléments clés de cette question!

Même emplacement est bon si vous pouvez le gérer, car il évite le besoin d’avoir une connaissance tribale (savoir où regarder), ou le besoin d’aller chercher où sont les choses.

— Rapidement maintenant

Ils n'ont peut-être pas besoin d'accéder au code, mais cela ne devrait pas leur nuire. Ils n'ont pas à le regarder. Les secrets ne devraient généralement pas être dans le contrôle de version de toute façon.

— BDSL

9

Dans l'entreprise avec laquelle je travaille, nous mettons la documentation dans SVN. Cependant, après quelques conflits et la nécessité de le partager, nous avons décidé de le transférer vers Mediawiki.

Au début, c’était trac, après cela déplacé vers Mediawiki car il était plus facile à utiliser ...

Le principal problème de SVN était le partage parce que nous avions un système d'autorisation pour SVN.

— confiq
source

2

Ne voulez-vous pas dire Mediawiki, le moteur de wiki utilisé par Wikipedia?

@ Martijn, je suppose donc

— Teo Klestrup Röijezon

@Martijn: Oui, édité

— Confiq

Je préférerais m'en tenir à un wiki plutôt que d'envoyer beaucoup de fichiers qui ne sont pas destinés à un SCM, mais qui ont plus à voir avec les préférences personnelles. Vous pouvez faire beaucoup plus avec cela. J'aime particulièrement Foswiki et son modèle basé sur un site Web / basé sur un projet. Heureux que quelqu'un ait choisi d'utiliser un wiki à cause de problèmes :) +1.

— Oeufcoque Penteano

9

Avoir plus que du code source dans un référentiel est une très bonne chose.

Il regroupe toutes vos ressources et transforme le projet en une entité cohérente et centralisée plutôt qu'en une collection dispersée de fichiers. Les collaborateurs / employés savent où trouver tout, plutôt que d'envoyer "Où puis-je modifier la documentation de la fonctionnalité x?" courriels.

Vous voudrez garder les choses organisées. Avoir un système pour séparer srcle imagesde le docs. Vous pouvez toujours ajouter un .gitignoreà un répertoire pour garder le référentiel et l'historique propres. Comme les commits Git sont basés sur des fichiers *, vous pouvez découpler les modifications de la source de celles de la documentation aussi fortement que vous le souhaitez.
Comme d'autres l'ont déjà dit, Git est idéal pour la gestion de versions de documentation, à condition qu'il soit basé sur du texte.
Je suis complètement d'accord; la documentation doit être versée juste à côté du code.

Ma crédibilité vient d’être un utilisateur de GitHub, de contribuer à un projet et d’en explorer de nombreux autres. D'après mon expérience, un projet complet et unifié est facile à distinguer d'un projet à moitié manquant. J'essaie de contenir tous mes projets dans des répertoires uniques autant que possible.

* Cela n’est pas tout à fait exact, car il existe des moyens de spécifier les parties d’un fichier à valider (en voici un exemple ).

— Tyler Wayne
source

4

Je suis venu ici avec une question similaire. Nous venons d'un environnement SVN, où il est évident de garder tous les documents liés à un projet dans le même référentiel. En raison de la nature de SVN, vous pouvez facilement consulter des parties du référentiel. Ainsi, si vous avez juste besoin du code source (par exemple, un déploiement de site Web), ce n'est pas un problème.

Avec Git, les choses sont différentes. Une extraction se situe toujours au niveau racine. Par conséquent, si vous souhaitez tout placer dans le même référentiel, vous obtiendrez toujours la même structure de répertoires. Une approche que j’ai rencontrée consiste à tout placer dans des branches distinctes, c’est-à-dire que vous avez des branches de code (qui sont généralement vos branches maître, de développement, etc.) et une branche doc, qui possède sa propre structure de répertoires distincte. Je ne suis pas encore sûr que ce soit la meilleure idée, mais c'est une suggestion qui contourne le problème qui, je suppose, est à la base de votre question.

— Eelke Blok
source

Différentes branches avec des structures de répertoires radicalement différentes dégagent une très mauvaise odeur de code. Je laisserais tout cela dans un rapport, ce qui permettrait aux contributeurs d'ajouter plus facilement un mélange de code et de documentation. En fait, la programmation alphabète (Google ça!) L'exige.

— tbc0

Lors de la distribution de packages, j'adhère au style .deb qui me permet de télécharger des fichiers exécutables sur tous les serveurs, tandis que ma boîte de développement contient également les packages de documentation.

— tbc0

1

J'utilise un wiki pour les documents internes ... je reçois une révision PLUS un accès important / une édition facile. Lorsque la documentation est désynchronisée, mettez-la à jour immédiatement. Pour la documentation destinée aux utilisateurs finaux, utilisez un outil professionnel tel que Madcap Flare. Ils utilisent un dialecte XML pour partager, composer et transformer la documentation.

— Michael Brown
source

-1

Dans le code, les pensées sont généralement séparées ligne par ligne. J'ai tendance à écrire de la documentation avec des lignes souples. Lorsque je valide ces fichiers, les lignes ont un paragraphe entier. Ce n'est pas très utile à lire git diff. C’est le problème que j’essayais de résoudre lorsque j’ai trouvé Google dans cette page. Merci à Arne Hartherz de m'avoir présenté à git diff --word-diff. Vous pourriez aimer git diff --color-wordsencore mieux.

— tbc0
source