Sollte die generierte Dokumentation in einem Git-Repository gespeichert werden?

49

Wenn Sie Tools wie jsdocs verwenden , werden statische HTML-Dateien und deren Stile in Ihrer Codebasis basierend auf den Kommentaren in Ihrem Code generiert.

Sollen diese Dateien in das Git-Repository eingecheckt oder mit .gitignore ignoriert werden?

Müllabfuhr
quelle
3
Möglicherweise gibt es ein Argument, um sie in einem GitHub-Repository zu speichern, da Sie den statischen HTML-Code mithilfe von Seiten veröffentlichen können . Obwohl dann eine ganz andere Reihe von Argumenten auftaucht, wie Sie sicherstellen, dass sie auf dem neuesten Stand sind usw.
Boris the Spider
21
Wenn Dateien generiert werden, sind sie definitionsgemäß keine Quellen .
chrylis -on strike-
3
Sie veröffentlichen, was Sie veröffentlichen möchten. Vor allem auf GitHub. Wenn Sie möchten, dass alle Benutzer eine generierte PDF-Datei oder ein generiertes Bild sehen, sollten Sie es einschließen, anstatt von allen zu erwarten, dass sie LaTeX installieren und selbst kompilieren. Zum Beispiel wäre dieses Repository nicht sehr gut, wenn es nicht die produzierten Bilder enthalten würde, nur die Projektdateien ...
Džuris
7
Wenn ich als Konsument von Bibliotheken von Drittanbietern 10 Mal eine Bibliothek ohne Online-Dokumentation sehe (egal ob in einem Unterordner des Repositorys oder in der Readme-Datei), klicke ich alle 10 Mal weg und überspringe diese Bibliotheken . Ich werde eine halbe Stunde lang nicht mit Doxygen rumspielen, nur um zu sehen, ob eine Bibliothek meine Bedürfnisse erfüllt.
Alexander

Antworten:

131

Wenn keine speziellen Anforderungen vorliegen, sollte keine Datei eingecheckt werden, die mithilfe anderer in die Versionskontrolle eingecheckter Dateien aus Build-Tools erstellt, neu erstellt, erstellt oder generiert werden kann. Wenn die Datei benötigt wird, kann sie von der anderen Datei (neu) erstellt werden Quellen (und würde normalerweise als ein Aspekt des Erstellungsprozesses sein).

Daher sollten diese Dateien mit .gitignore ignoriert werden.

1201ProgramAlarm
quelle
4
Dies kann jedoch von Versionen der Build-Tools oder sogar von der Verfügbarkeit der Build-Tools abhängen (um z. B. einige Dateien zu generieren, ist eine alte Version eines Build-Tools erforderlich). Wie gehst du damit um? Kannst du es in deiner Antwort ansprechen?
Peter Mortensen
27
@PeterMortensen Wenn Sie ein Artefakt benötigen, das mit einer speziellen Version von buld tools erstellt wurde, erstellen Sie es mit der Version von Build tools, die Sie benötigen. Ein solches Bedürfnis ist entweder a) von Ihnen selbst entdeckt, in welchem ​​Fall Sie allein sind; b) in README dokumentiert ("Sie benötigen zwei spezielle Versionen von Doxygen ..."); c) von den Build-Skripten behandelt werden (sie prüfen die verfügbaren Versionen der Build-Tools und verhalten sich entsprechend). In jedem Fall bezieht sich die Quellcodeverwaltung auf Quellen und nicht auf Buildartefakte.
Joker_vD
2
Ich denke, diese Antwort ist nur dann sinnvoll, wenn ein Continuous Deployment Server die Dokumentation auf leicht zugängliche Weise erstellt und veröffentlicht. Andernfalls ist es von großem Wert, die Dokumente im Repo zu "cachen", um die Zugänglichkeit zu verbessern. Kein Benutzer sollte sich mit Ihren Build-Skripten herumschlagen müssen, um die Dokumentation Ihrer Software zu sehen.
Alexander
4
@Alexander Würdest du auch das eingebaute Binary in das Repo stellen? Die Dokumentation wird erstellt. Sie nehmen die erstellte Dokumentation und machen sie irgendwo zugänglich.
1201ProgramAlarm
5
@ 1201ProgramAlarm "Würden Sie auch die eingebaute Binärdatei in das Repo einfügen?" Nein, denn eine erstellte Binärdatei hat im Vergleich zur Dokumentation nur einen geringen Anfangswert für Benutzer, die in GitHub surfen. "Sie nehmen die erstellte Dokumentation und machen sie irgendwo zugänglich." Solange es öffentlich gehostet und sichtbar verknüpft ist, ist es großartig. Es ist wahrscheinlich der beste Fall.
Alexander
23

Meine Regel ist, dass, wenn ich ein Repository klone und einen "Build" -Button drücke, nach einer Weile alles erstellt wird. Um dies für Ihre generierte Dokumentation zu erreichen, haben Sie zwei Möglichkeiten: Entweder ist jemand dafür verantwortlich, diese Dokumente zu erstellen und in git zu platzieren, oder Sie dokumentieren genau die Software, die ich auf meinem Entwicklungscomputer benötige, und Sie stellen sicher, dass Sie auf „Erstellen“ klicken. button erstellt die gesamte Dokumentation auf meinem Computer.

Im Fall der generierten Dokumentation, bei der jede einzelne Änderung, die ich an einer Header-Datei vornehme, die Dokumentation ändern sollte, ist es besser, dies auf jedem Entwickler-Computer zu tun, da ich die ganze Zeit korrekte Dokumentation möchte, nicht nur, wenn jemand sie aktualisiert hat. Es gibt andere Situationen, in denen das Generieren zeitaufwendig und kompliziert sein kann und Software erforderlich ist, für die Sie nur eine Lizenz haben. In diesem Fall ist es besser, einer Person die Verantwortung zu übertragen, die Dinge in git zu packen.

@ Kurt Simpson: Es ist viel besser, alle Softwareanforderungen dokumentiert zu haben, als ich es an vielen Stellen gesehen habe.

gnasher729
quelle
7
Dokumentieren Sie nicht, welche Software jemand für den Build benötigt (oder dokumentieren Sie zumindest nicht nur ): Lassen Sie das Build-Skript dem Benutzer mitteilen, was er vermisst, oder installieren Sie es selbst, wenn dies sinnvoll ist. In den meisten meiner Repos kann jeder halbwegs kompetente Entwickler einfach ./Testeinen Build ausführen und erhalten oder gute Informationen darüber, was er tun muss, um einen Build zu erhalten.
Curt J. Sampson
5
Ich stimme nicht wirklich zu, dass das Einfügen von generierter Dokumentation in git in dem von Ihnen angegebenen Fall gut sein kann. Aus diesem Grund haben wir Artefakte und Archive.
Sulthan,
Das ist deine Regel und es ist eine gute Regel und ich mag es. Aber andere können ihre eigenen Regeln aufstellen.
Emory
Ich denke, Sie meinen "einen Build-Befehl ausführen", da es auf Ihrem Computer keine Build-Schaltfläche geben würde. ... es sei denn, Sie erwarten, dass der gesamte Build in eine IDE integriert wird, was völlig unzumutbar ist.
jpmc26
@ jpmc26 Ich finde es völlig vernünftig, den gesamten Build in eine IDE zu integrieren. Die Schaltfläche zum Erstellen auf meinem Computer ist Befehl-B.
gnasher729
14

Diese Dateien sollten nicht eingecheckt werden, da die zu generierenden Daten bereits vorhanden sind. Sie möchten Daten nicht zweimal speichern (DRY).

Wenn Sie ein CI-System haben, können Sie möglicherweise die Dokumente erstellen und für diesen Build speichern / auf einem Webserver veröffentlichen.

Tvde1
quelle
4

Ein Vorteil, wenn Sie sie in einem Repository haben (entweder dasselbe oder ein anderes, vorzugsweise automatisch generiertes), ist, dass Sie dann alle Änderungen an der Dokumentation sehen können. Manchmal sind diese Unterschiede leichter zu lesen als die Unterschiede zum Quellcode (insbesondere, wenn Sie sich nur um Spezifikationsänderungen kümmern, nicht um eine Implementierung).

In den meisten Fällen ist es jedoch nicht erforderlich, sie in der Quellcodeverwaltung zu haben, wie in den anderen Antworten erläutert.

Paŭlo Ebermann
quelle
1
Das würde so ziemlich einen Pre-Commit-Hook in jedem Repo erfordern, der zum Erstellen von Commits verwendet wird. Wenn der Dokumentationserstellungsprozess nicht vollständig automatisiert ist, erhalten Sie Festschreibungen, bei denen die Dokumentation nicht mit dem Code synchronisiert ist. Und diese fehlerhaften Commits beeinträchtigen die Verständlichkeit mehr als eine nicht festgeschriebene Dokumentation.
14.
1
Dies muss nicht im Festschreibungsstadium sein. Es könnte leicht eine Downstream- / CI- / Jenkins-Aufgabe sein, sie jedes Mal zu veröffentlichen, wenn sie als speicherwürdig eingestuft werden. Dies kann durchaus jedes Commit sein, aber die Entscheidung sollte ohne triftigen Grund entkoppelt werden. Zumindest sehe ich das so.
Einmal
3

Ignoriert. Sie möchten, dass die Benutzer des Repos sie trotzdem neu erstellen können, und die Komplexität der Sicherstellung, dass die Dokumente immer synchron sind, wird aufgehoben. Es gibt keinen Grund, die gebauten Artefakte nicht an einem Ort zu bündeln, wenn Sie alles an einem Ort haben möchten und nichts bauen müssen. Allerdings sind Source-Repos kein guter Ort, um dies zu tun, da die Komplexität dort mehr schmerzt als an den meisten anderen Orten.

Einer
quelle
2

Dies hängt von Ihrem Bereitstellungsprozess ab. Das Festschreiben generierter Dateien in einem Repository ist jedoch eine Ausnahme und sollte nach Möglichkeit vermieden werden. Wenn Sie beide der folgenden Fragen mit Ja beantworten können , ist das Einchecken Ihrer Dokumente möglicherweise eine gültige Option:

  • Sind die Dokumente eine Voraussetzung für die Produktion?
  • Fehlen Ihrem Bereitstellungssystem die erforderlichen Tools zum Erstellen der Dokumente?

Wenn diese Bedingungen zutreffen, werden Sie wahrscheinlich mit einem Legacy-System oder einem System mit speziellen Sicherheitsbeschränkungen bereitgestellt. Alternativ können Sie die generierten Dateien in einen Release-Zweig schreiben und den Master-Zweig sauber halten.

Trendfischer
quelle
1
Das Festschreiben generierter Dateien in einem Release-Zweig funktioniert nicht in allen Situationen, es gibt jedoch eine Reihe, insbesondere bei statischen Websites, die mit Markdown erstellt wurden. Dies ist eine hervorragende Lösung. Ich mache es oft genug, dass ich ein spezielles Tool erstellt habe , um solche Commits im Rahmen des Erstellungsprozesses einfach zu generieren.
Curt J. Sampson
2

Es hängt davon ab, ob. Wenn diese Dokumente:

  • Muss Teil des Repository sein, so wie das Repository, readme.mddann ist es vorzuziehen, sie im Git- Repository zu belassen. Weil es schwierig sein kann, diese Situationen automatisiert zu handhaben.

  • Wenn Sie keine automatisierte Möglichkeit zum Erstellen und Aktualisieren haben, wie z. B. ein CI-System, und es für das allgemeine Publikum gedacht ist, sollten Sie es im Git-Repo behalten.

  • Es braucht viel Zeit, um sie zu bauen, dann ist es gerechtfertigt, sie zu behalten.

  • Sie sind für das allgemeine Publikum gedacht (wie das Benutzerhandbuch) und es dauert eine beträchtliche Zeit, sie zu erstellen, während auf Ihre vorherigen Dokumente nicht mehr zugegriffen werden kann (offline). Dann ist es gerechtfertigt, sie im Git-Repo zu behalten.

  • Sollen für das allgemeine Publikum gesehen werden und muss eine Geschichte seiner Änderungen / Entwicklungen zeigen, könnte es einfacher sein, frühere Dokumentversionen festzuschreiben und die neue zu erstellen / festzuschreiben, die mit der vorherigen verknüpft ist. Gerechtfertigt.

  • Hat eine bestimmte akzeptierte Begründung für die Verpflichtung des gesamten Teams, ist es gerechtfertigt, sie im Git-Repo zu belassen. (Wir kennen Ihren Kontext nicht, Sie und Ihr Team)

In jedem anderen Szenario sollte es sicher ignoriert werden.

Wenn es jedoch gerechtfertigt ist, sie im Git-Repo zu belassen, könnte dies ein Zeichen für ein weiteres größeres Problem sein, mit dem Ihr Team konfrontiert ist. (Kein CI-System oder ähnliches, schreckliche Leistungsprobleme, Ausfallzeiten beim Erstellen usw.)

throawableAccount2892391
quelle
1

Aus Gründen der Versionskontrolle sollten nur "primäre Objekte" in einem Repository gespeichert werden, keine "abgeleiteten Objekte".

Es gibt Ausnahmen von der Regel: Es gibt nämlich Konsumenten des Repositorys, die die abgeleiteten Objekte benötigen und von denen vernünftigerweise nicht erwartet wird, dass sie über die erforderlichen Tools verfügen, um sie zu generieren. Andere Überlegungen spielen eine Rolle, wie ist die Menge des Materials unhandlich? (Wäre es besser für das Projekt, wenn alle Benutzer über die Tools verfügen?)

Ein extremes Beispiel hierfür ist ein Projekt, das eine seltene Programmiersprache implementiert, deren Compiler in dieser Sprache geschrieben ist (bekannte Beispiele sind Ocaml oder Haskell)). Befindet sich nur der Compiler-Quellcode im Repository, kann er von niemandem erstellt werden. Sie haben keine kompilierte Version des Compilers, die sie auf der virtuellen Maschine ausführen können, sodass sie den Quellcode des Compilers kompilieren können. Darüber hinaus werden die neuesten Funktionen der Sprache sofort in der Compiler-Quelle selbst verwendet, sodass immer die aktuellste Version des Compilers erforderlich ist, um sie zu erstellen: Eine separat erhältliche, ein Monat alte ausführbare Compiler-Datei kompiliert den aktuellen Code nicht, da der Code verwendet Sprachfunktionen, die es vor einem Monat noch nicht gab. In diesem Fall muss die kompilierte Version des Compilers mit ziemlicher Sicherheit in das Repository eingecheckt und auf dem neuesten Stand gehalten werden.

Kaz
quelle