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

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?

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.

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.

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.

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.

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.

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.

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.)

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.