Sollte Git für die Dokumentation und das Projektmanagement verwendet werden? Sollte sich der Code in einem separaten Repository befinden?

68

Ich starte ein Git-Repository für ein Gruppenprojekt. Ist es sinnvoll, Dokumente im selben Git-Repository wie Code zu speichern ? Dies steht anscheinend in Konflikt mit der Art des Git-Revisionsflusses.

Hier ist eine Zusammenfassung meiner Frage (n):

  • Ist der Git-Revisionsstil verwirrend, wenn sowohl Code als auch Dokumente im selben Repository eingecheckt werden ? Erfahrungen damit?

  • Ist Git gut für die Versionskontrolle von Dokumentationen geeignet?

  • Ich frage NICHT , ob ein Revisionskontrollsystem im Allgemeinen für die Dokumentation verwendet werden soll oder nicht - es sollte.

Vielen Dank für das bisherige Feedback!

git version-control project-management EmpireJones
quelle
Ah, okay ... danke für die Klarstellung. Ich verstehe nicht, warum es ein Problem sein würde, aber ich habe keine persönlichen Erfahrungen mit GIT (nur ein theoretisches Verständnis), also lasse ich jemanden mit direkteren Erfahrungen diese Frage beantworten.
Flimzy
1
Ich verstehe nicht ganz, wie das Thema ist. Sie sprechen über Softwaredokumentation und das Festschreiben mit einem DVCS
Tim Post
Kommt wohl auf die Dokumentation und deine Bedürfnisse an. Benötigen Sie Unterschiede und ist es in einem Format, das damit umgehen kann? Wenn Git die erforderlichen Dienste sicher gibt. Beats mit einem separaten Dokumentenmanagementsystem ...
Rig
Wenn Ihre Dokumentation im Klartext vorliegt - in Ordnung. Wenn es sich um ein Binärformat handelt, benötigen Sie im Wesentlichen ein Versionskontrollsystem, das das Binärformat versteht - dies ist die Lieferantenbindung in ihrer reinsten Form.
related: Welcher Teil Ihres Projekts sollte sich in der Quellcodeverwaltung befinden?
gnat

Antworten:

53

Wir speichern die Dokumentation ständig in SVN. Tatsächlich ist unser gesamtes Benutzerhandbuch in LaTeX geschrieben und in SVN gespeichert. Wir haben uns speziell für LaTeX entschieden, da es sich um eine textbasierte Sprache handelt und es einfach ist, zeilenweise Unterschiede anzuzeigen.

Wir speichern auch einige nicht textformatierte Dateien, wie Microsoft Office-DOC-Dateien, Tabellenkalkulationsdateien, ZIP-Dateien usw., wenn dies erforderlich ist. Einige Vorteile eines RCS gehen jedoch verloren, wenn Sie die inkrementellen Dateien nicht sehen können Unterschiede.

Der Schlüssel ist wirklich sicherzustellen, dass Ihre Dokumentation gut organisiert ist, damit die Leute die Dokumentation (und die Quelle) finden (und aktualisieren) können, wenn sie sie benötigen.

Fadenscheinig
quelle
11
Wenn Sie ein Microsoft-Shop sind, unterstützt TortoiseSVN zeilenweise Unterschiede in MS Office.
Phil
2
Das Löschen von binären Dokumentenformaten würde die Welt verbessern. o Da es sich bei den Dokumenten um Klartext handelt, sollte es auch mit einem DVCS keine wirklichen Probleme geben.
Kai Inkinen
Oh, und zum ersten Mal hörte ich von TortoiseSVN und doc-Dateien, also +1 dafür. Ich frage mich, ob das in Zukunft auf Tortoise [AnyDVCS] landen wird.
Kai Inkinen
@Phil: Wie schafft TortoiseSVN das? Ist der doc-diff-Viewer in den SVN-Client integriert oder kann er unabhängig verwendet werden?
Flimzy
1
Eine coole Option wäre, Pandoc zu verwenden, damit sich der größte Teil Ihrer Dokumentation in Markdown befindet, aber die entscheidenden Teile können immer noch TeX verwenden. Da der Markdown in LaTeX kompiliert wird, sehen die Ergebnisse gleich aus. Auf diese Weise können Sie es jedoch auch in andere Formate exportieren und die Quelle leichter lesen.
Tikhon Jelvis
22

Nun, es hängt davon ab, welches Format Sie für die Dokumentation verwenden. Wenn es etwas Textbasiertes ist, ist alles gut.

Git kann auch binären Inhalt speichern und Sie können Revisionen verfolgen, aber die Diff-Ausgabe macht keinen Sinn.

Es ist auch möglich, die Dokumentation im Code selbst zu speichern, wie z. B. perldoc pod. Java verfügt auch über ein Format / eine Annotation dafür.

cstamas
quelle
Ich bin damit einverstanden, dass es zwar möglich ist, Nicht-Text-Dokumentation zu speichern, aber Git ist viel besser, wenn Sie stattdessen Text speichern. Es ist die Rede von einem Diff-Treiber, der weiß, wie man Word-Dokumente (oder ähnliche) unterscheidet, aber ich bin nicht sicher, ob es implementiert wurde oder nicht
Sverre Rabbelier,
Ich dachte, Word verschob ihr Format von Binär zu XML.
Cledoux
3
@ karategeek6 Das XML-Format von Word ist nicht für Menschen lesbar. Und eine Textzeile entspricht nicht einmal annähernd einer Zeile von Words XML. Es könnte also genauso gut binär sein.
Sie können Word anweisen, Ihre Ausgabe in nicht komprimiertem XML zu speichern. Wählen Sie Save Asund dann Word XML Document (*.xml)anstelle der Standardeinstellung Word Document (*.docx). Das XML ist ziemlich komplex, daher ist dies keine Garantie dafür, dass die Änderungen leicht lesbar sind, aber zumindest nicht binär.
Kyralessa
> aber die diff Ausgabe macht keinen Sinn. Falls es Unterschiede gibt, können wir zwei Versionen eines Dokuments nebeneinander öffnen und mit unseren Augen vergleichen :)
Luke,
14

Ich kann mir nicht vorstellen, warum es Ihrer Meinung nach Probleme bei der Verwendung von Git oder einem anderen Versionskontrollsystem für die Dokumentation gibt. Wie der Quellcode sollte auch die Dokumentation einen vollständigen Verlauf aufweisen und die Möglichkeit haben, bei Bedarf auf eine frühere Version zurückzugreifen. Ein Versionskontrollsystem ist dafür perfekt.


quelle
6
Nur wenn die Dokumentation in Textform vorliegt. Binäre Blobs profitieren nicht vollständig von der Versionskontrolle.
2
@ ThorbjørnRavnAndersen: Auch wenn Sie kein binärspezifisches Versionssystem haben, ist es wahrscheinlich besser, auch Binärdateien in Git zu speichern, als sie selbst zu erstellen.
Tikhon Jelvis
@TikhonJelvis Ich habe nicht gefragt, ob es eine gute Idee ist, Binärdateien in git abzulegen - wenn es sich um die ursprünglichen Artefakte handelt, ist es das. Versuchen Sie jedoch, "git diff" für Word-Dokumente auszuführen.
@ user1249: Sie könnten 2 Revisionen auf den Desktop "exportieren", my_docs_rev15.docx und my_docs_rev14.docx sagen und sie dann nebeneinander öffnen und mit Ihren Augen und Ihrem Gehirn vergleichen, es ist nicht so schwer :)
Luke
14

Es ist klar, dass die Verwendung eines Versionskontrollsystems zum Speichern von Dokumenten ein Nobrainer ist. Der interessantere Teil der Frage ist, ob es sinnvoll ist, Dokumente am selben Speicherort als Quellcode zu speichern. Das mögliche Problem hierbei ist, dass es in diesem Fall schwierig sein kann, unterschiedliche Zugriffsrechte für Code und Dokumentation festzulegen. In vielen Fällen benötigen Mitarbeiter Zugriff auf Dokumente, jedoch nicht auf den Quellcode, z. B. Marketing- oder BA-Abteilungen.

Ma99uS
quelle
3
Ja, der Aspekt "gleicher Ort" ist einer der Schlüsselbereiche dieser Frage!
Derselbe Ort ist gut, wenn Sie ihn verwalten können, da es nicht erforderlich ist, Stammeskenntnisse zu haben (zu wissen, wo sie suchen müssen) oder nach dem Ort zu suchen, an dem sich das Zeug befindet.
quick_now
Sie benötigen möglicherweise keinen Zugriff auf den Code, aber es sollte ihnen nicht schaden, diesen Zugriff zu haben. Sie müssen es nicht ansehen. Geheimnisse sollten ohnehin nicht in der Versionskontrolle sein.
BDSL
9

In der Firma, in der ich arbeite, haben wir die Dokumentation in SVN abgelegt. Nach ein paar Konflikten und der Notwendigkeit, es zu teilen, haben wir uns entschlossen, es auf Mediawiki zu verschieben.

Zuerst war es Trac, nachdem es auf Mediawiki verschoben wurde, weil es einfacher zu bedienen war ...

Das Hauptproblem bei SVN war die gemeinsame Nutzung, da wir ein Autorisierungssystem für SVN hatten.

confiq
quelle
2
Meinen Sie nicht Mediawiki, die Wiki-Engine, die Wikipedia verwendet?
@ Martijn, ich würde davon ausgehen
Teo Klestrup Röijezon
@ Martijn: Ja, bearbeitet
Confiq
Ich würde mich lieber an ein Wiki halten, als viele Dateien zu senden, die nicht an ein SCM gerichtet sind, aber das hat mehr mit persönlichen Vorlieben zu tun. Sie können noch viel mehr damit anfangen. Ich mag besonders Foswiki und deren website-basierte / projektbasierte Vorlage. Ich bin froh, dass jemand darauf hingewiesen hat, dass er sich aufgrund von Problemen für die Verwendung eines Wikis entschieden hat :) +1.
Oeufcoque Penteano
9

  • Es ist eine sehr gute Sache, mehr als nur Quellcode in einem Repository zu haben.

    Es gruppiert alle Ihre Ressourcen und verwandelt das Projekt in eine zusammenhängende, zentralisierte Einheit und nicht in eine verstreute Sammlung von Dateien. Mitwirkende / Mitarbeiter wissen, wo sie alles finden, anstatt zu senden: "Wo ändere ich die Dokumentation für Feature x?" E-Mails.

    Sie wollen die Dinge organisiert halten. Haben Sie ein System zum Trennen srcder imagesvon der docs. Sie können .gitignoreeinem Verzeichnis jederzeit ein hinzufügen , um das Repository und den Verlauf sauber zu halten. Da Git-Commits dateibasiert sind *, können Sie Quelländerungen von Dokumentationsänderungen so stark entkoppeln, wie Sie möchten.

  • Wie bereits erwähnt, eignet sich Git hervorragend für die Versionsverwaltung von Dokumentationen, sofern es textbasiert ist.

  • Ich stimme vollkommen zu; Die Dokumentation sollte direkt neben dem Code versioniert werden.

Meine Glaubwürdigkeit beruht darauf, ein GitHub-Benutzer zu sein, an einem Projekt mitzuwirken und viele andere zu erkunden. Nach meiner Erfahrung lässt sich ein vollständiges, einheitliches Projekt leicht von einem halbwegs fehlenden Projekt unterscheiden. Ich versuche, alle meine Projekte nach Möglichkeit in einzelne Verzeichnisse zu packen.

* Dies ist nicht ganz korrekt, da es Möglichkeiten gibt, Teile einer Datei anzugeben , die festgeschrieben werden sollen ( hier ein Beispiel ).

Tyler Wayne
quelle
4

Ich bin mit einer ähnlichen Frage hergekommen. Wir kommen aus einer SVN-Umgebung, in der es im Grunde genommen ein Kinderspiel ist, alle Materialien, die sich auf ein Projekt beziehen, im selben Repository zu speichern. Aufgrund der Natur von SVN können Sie problemlos Teile des Repositorys auschecken. Wenn Sie also nur den Quellcode benötigen (z. B. eine Website-Bereitstellung), ist dies kein Problem.

Bei Git ist das anders. Ein Checkout befindet sich immer auf der Root-Ebene. Wenn Sie also alles im selben Repository ablegen möchten, erhalten Sie immer die gleiche Verzeichnisstruktur. Ein Ansatz, auf den ich gestoßen bin, besteht darin, alles in separate Zweige zu unterteilen, dh Sie haben Code-Zweige (die normalerweise Ihre normalen Master-, Entwicklungs- usw. Zweige sind) und einen Doc-Zweig, der eine eigene, separate Verzeichnisstruktur hat. Ich bin mir noch nicht sicher, ob das die beste Idee ist, aber es ist ein Vorschlag, der das Problem umgeht, von dem ich mir vorstelle, dass es die Grundlage Ihrer Frage ist.

Eelke Blok
quelle
Unterschiedliche Branchen mit radikal unterschiedlichen Verzeichnisstrukturen haben für mich einen sehr schlechten Codegeruch. Ich würde alles in einem Repo belassen, was es den Mitwirkenden einfacher macht, eine Mischung aus Code und Dokumentation hinzuzufügen. In der Tat verlangt dies die Alphabetisierung (Google that!).
tbc0
Beim Verteilen von Paketen bin ich teilweise an dem .deb-Stil interessiert, mit dem ich ausführbare Dateien auf alle Server herunterladen kann, während meine Entwicklungsbox auch die Dokumentationspakete enthält.
tbc0
1

Ich benutze ein Wiki für interne Dokumente ... bekomme Revision PLUS prominenten Zugriff / einfache Bearbeitung. Wenn die Dokumentation nicht mehr synchron ist, aktualisieren Sie sie sofort. Betrachten Sie für die Endbenutzerdokumentation ein professionelles Tool wie Madcap Flare. Sie verwenden einen XML-Dialekt zum Teilen, Verfassen und Transformieren von Dokumentation.

Michael Brown
quelle
-1

Im Code werden Gedanken normalerweise zeilenweise getrennt. Ich neige dazu, Dokumentation mit weichen Zeilenumbrüchen zu schreiben. Wenn ich diese Dateien festschreibe, sind die Zeilen einen ganzen Absatz lang. Das ist nicht sehr nützlich zum Einlesen git diff. Das ist das Problem, das ich zu lösen versuchte, als ich googelte und diese Seite fand. Vielen Dank an Arne Hartherz , der mich vorgestellt hat git diff --word-diff. Das könnte dir git diff --color-wordsnoch besser gefallen .

tbc0
quelle