Czy wygenerowana dokumentacja powinna być przechowywana w repozytorium Git?

49

Kiedy używasz narzędzi takich jak jsdocs , generuje on statyczne pliki HTML i ich style w bazie kodu na podstawie komentarzy w kodzie.

Czy te pliki powinny być rejestrowane w repozytorium Git, czy powinny być ignorowane za pomocą .gitignore?

zbieranie śmieci
źródło
3
Może istnieć argument, aby przechowywać je w repozytorium GitHub, ponieważ można publikować statyczny kod HTML za pomocą stron . Chociaż wtedy powstaje zupełnie osobny zestaw argumentów na temat tego, jak zapewnić ich aktualność itp.
Boris the Spider
21
Jeśli pliki są generowane, to z definicji nie są źródłowe .
Chrylis
3
Publikujesz to, co chcesz opublikować. Zwłaszcza na GitHub. Jeśli chcesz, aby wszyscy zobaczyli wygenerowany plik PDF lub obraz, powinieneś dołączyć go zamiast oczekiwać, że wszyscy zainstalują LaTeX i sami go skompilują. Na przykład to repozytorium nie byłoby zbyt dobre, gdyby nie zawierało wytworzonych obrazów, tylko pliki projektu ...
Džuris
7
Jako konsument bibliotek stron trzecich, spośród 10 razy, kiedy widzę bibliotekę bez dokumentacji online (czy to w podfolderze repozytorium, czy w linkach z pliku readme), klikam i pomijam te biblioteki, wszystkie 10 razy . Nie zamierzam przez pół godziny bawić się z Doxygenem, żeby sprawdzić, czy biblioteka spełnia moje potrzeby.
Alexander

Odpowiedzi:

131

Bez konkretnej potrzeby, żaden plik, który można zbudować, odtworzyć, skonstruować lub wygenerować z narzędzi do kompilacji przy użyciu innych plików zapisanych w kontroli wersji, nie powinien być rejestrowany. Gdy plik jest potrzebny, można go (ponownie) zbudować z drugiego źródła (i normalnie byłoby to pewien aspekt procesu kompilacji).

Te pliki należy więc zignorować za pomocą .gitignore.

1201ProgramAlarm
źródło
4
Może to jednak zależeć od wersji narzędzi do budowania lub nawet dostępności narzędzi do budowania (np. Do wygenerowania niektórych plików wymagana jest stara wersja narzędzia do budowania). Jak sobie z tym poradzisz? Czy potrafisz rozwiązać ten problem w swojej odpowiedzi?
Peter Mortensen
27
@PeterMortensen Jeśli potrzebujesz artefaktu zbudowanego ze specjalnej wersji narzędzi buld, budujesz go za pomocą potrzebnej wersji narzędzi do budowania. Taka potrzeba jest albo a) odkryta przez ciebie, w którym to przypadku jesteś sam; b) udokumentowane w README („Będziesz potrzebował dwóch z 2 konkretnymi wersjami doxygen zainstalowanymi ...”); c) obsługiwane przez skrypty kompilacji (sprawdzają dostępne wersje narzędzi kompilacji i działają odpowiednio). W każdym razie kontrola źródła dotyczy źródeł, a nie artefaktów kompilacji.
Joker_vD
2
Myślę, że ta odpowiedź jest wykonalna tylko wtedy, gdy serwer ciągłego wdrażania buduje i publikuje dokumentację w łatwo dostępny sposób. W przeciwnym razie wielką zaletą „buforowania” dokumentów w repozytorium jest poprawa dostępności. Żaden użytkownik nie powinien zmarnować skryptów kompilacji, aby zobaczyć dokumentację oprogramowania.
Alexander
4
@Alexander Czy umieściłbyś również wbudowany plik binarny w repozytorium? Dokumentacja jest zbudowana. Bierzesz zbudowaną dokumentację i udostępniasz ją gdzieś.
1201ProgramAlarm
5
@ 1201ProgramAlarm „Czy umieściłbyś również wbudowany plik binarny w repozytorium?” Nie, ponieważ wbudowany plik binarny ma niską wartość początkową dla osób przeglądających GitHub w porównaniu z dokumentacją. „Bierzesz zbudowaną dokumentację i udostępniasz ją gdzieś”. Tak długo, jak to jest publicznie hostowane, widocznie powiązane, tak, to świetnie. To chyba najlepszy przypadek.
Alexander
23

Moją zasadą jest, że kiedy klonuję repozytorium i naciskam przycisk „buduj”, to po chwili wszystko jest budowane. Aby to osiągnąć w wygenerowanej dokumentacji, masz dwie możliwości: albo ktoś jest odpowiedzialny za utworzenie tych dokumentów i umieszczenie ich w git, albo udokumentujesz dokładnie to, czego potrzebuję na moim komputerze programistycznym, i upewniasz się, że naciskasz „build” przycisk buduje całą dokumentację na moim komputerze.

W przypadku generowanej dokumentacji, gdzie każda pojedyncza zmiana, którą dokonam w pliku nagłówkowym, powinna zmienić dokumentację, lepiej jest to zrobić na komputerze każdego programisty, ponieważ chcę zawsze poprawnej dokumentacji, nie tylko wtedy, gdy ktoś ją zaktualizuje. Istnieją inne sytuacje, w których generowanie czegoś może być czasochłonne, skomplikowane, wymagać oprogramowania, na które masz tylko jedną licencję itp. W takim przypadku powierzenie jednej osobie odpowiedzialności za włożenie rzeczy do git jest lepsze.

@Curt Simpson: uwzględniając wszystkie wymagania programowe udokumentowane jest o wiele lepsze niż widziałem w wielu miejscach.

gnasher729
źródło
7
Nie dokumentuj, jakie oprogramowanie ktoś potrzebuje do kompilacji (a przynajmniej nie tylko dokumentuj): spraw, aby skrypt kompilacji powiedział użytkownikowi, czego brakuje, lub nawet sam go zainstaluj, jeśli jest to uzasadnione. W większości moich repozytoriów każdy w połowie kompetentny programista może po prostu uruchomić ./Testi uzyskać kompilację lub uzyskać dobre informacje o tym, co musi zrobić, aby uzyskać kompilację.
Curt J. Sampson
5
Naprawdę nie zgadzam się z tym, że umieszczenie wygenerowanej dokumentacji w git może być dobre w przypadku, który określisz. Dlatego mamy artefakty i archiwa.
Sulthan
To jest twoja reguła i jest to dobra reguła i podoba mi się. Ale inni mogą tworzyć własne reguły.
emory
Myślę, że masz na myśli „uruchom polecenie kompilacji”, ponieważ na komputerze nie będzie przycisku kompilacji. ... Chyba że oczekujesz, że cała kompilacja zostanie zintegrowana z IDE, co jest całkowicie nieuzasadnione.
jpmc26
@ jpmc26 Uważam, że całkowicie uzasadnione jest zintegrowanie całej kompilacji z IDE. Przycisk kompilacji na moim komputerze to Command-B.
gnasher729
14

Pliki te nie powinny być rejestrowane, ponieważ dane do ich wygenerowania są już obecne. Nie chcesz przechowywać danych dwa razy (DRY).

Jeśli masz system CI, być może mógłbyś zbudować te dokumenty i zapisać je dla tej kompilacji / opublikować na serwerze WWW.

Tvde1
źródło
4

Jedną z zalet posiadania ich w jakimś repozytorium (tym samym lub innym, najlepiej generowanym automatycznie) jest to, że można wtedy zobaczyć wszystkie zmiany w dokumentacji. Czasami te różnice są łatwiejsze do odczytania niż różnice do kodu źródłowego (szczególnie jeśli zależy Ci tylko na zmianach specyfikacji, a nie implementacji).

Ale w większości przypadków kontrolowanie źródła nie jest potrzebne, jak wyjaśniono w innych odpowiedziach.

Paŭlo Ebermann
źródło
1
To prawie wymagałoby haczyka poprzedzającego zatwierdzenie w każdym repozytorium używanym do tworzenia zatwierdzeń. Ponieważ jeśli proces generowania dokumentacji nie jest w pełni zautomatyzowany, otrzymasz zatwierdzenia, w których dokumentacja nie jest zsynchronizowana z kodem. A te złamane zobowiązania bardziej zaszkodzą zrozumiałości niż nieproszona dokumentacja.
cmaster
1
Nie musi to być na etapie zatwierdzania. Publikowanie ich za każdym razem, gdy zostaną uznane za warte przechowywania, może być z łatwością zadaniem niższego szczebla / CI / Jenkins. Może to być każde zatwierdzenie, ale decyzja powinna zostać oddzielona bez uzasadnionego powodu. A przynajmniej tak to widzę.
ANone
3

Ignorowane Będziesz chciał, aby użytkownicy repozytorium i tak mogli je odbudować, a to eliminuje złożoność upewnienia się, że dokumenty są zawsze zsynchronizowane. Nie ma powodu, aby nie budować artefaktów w jednym miejscu, jeśli chcesz mieć wszystko w jednym miejscu i nie musisz niczego budować. Jednak repozytorium źródeł nie jest tak naprawdę dobrym miejscem do zrobienia tego, ponieważ złożoność boli bardziej niż większość miejsc.

ANone
źródło
2

To zależy od procesu wdrażania. Ale zatwierdzanie wygenerowanych plików w repozytorium jest wyjątkiem i powinno się go unikać, jeśli to możliwe. Jeśli możesz odpowiedzieć na oba poniższe pytania za pomocą Tak , sprawdzanie dokumentów może być prawidłową opcją:

  • Czy dokumenty są wymagane do produkcji?
  • Czy w Twoim systemie wdrażania brakuje narzędzi niezbędnych do tworzenia dokumentów?

Jeśli te warunki są spełnione, prawdopodobnie wdrażasz przy użyciu starszego systemu lub systemu ze specjalnymi ograniczeniami bezpieczeństwa. Alternatywnie możesz zatwierdzić wygenerowane pliki w gałęzi wydania i utrzymać gałąź master w czystości.

Trendfischer
źródło
1
Zatwierdzanie wygenerowanych plików w gałęzi wydania nie działa w każdej sytuacji, ale jest ich pewna liczba, szczególnie w przypadku takich rzeczy, jak statyczne strony internetowe zbudowane z markdown, gdzie jest to doskonałe rozwiązanie. Robię to wystarczająco często, aby zbudować specjalne narzędzie do łatwego generowania takich zatwierdzeń w ramach procesu kompilacji.
Curt J. Sampson
2

To zależy. Jeśli te dokumenty:

  • Musi być częścią repozytorium, tak jak readme.md, wtedy najlepiej jest przechowywać je w repozytorium git. Ponieważ zautomatyzowane radzenie sobie z tymi sytuacjami może być trudne.

  • Jeśli nie masz zautomatyzowanego sposobu ich budowania i aktualizowania, takiego jak system CI, i jest on przeznaczony do wyświetlania dla ogółu odbiorców, najlepiej jest zachować je w repozytorium git.

  • Zbudowanie ich zajmuje dużo czasu, a następnie uzasadnione jest ich zachowanie.

  • Są przeznaczone do wyświetlania dla szerokiej publiczności (jak instrukcja obsługi) i zajmuje dużo czasu, a poprzednie dokumenty stają się niedostępne (offline), więc uzasadnione jest utrzymanie ich w repozytorium git.

  • Są przeznaczone do obejrzenia dla szerokiej publiczności i muszą pokazać historię zmian / ewolucji, łatwiej byłoby zachować poprzednie wersje dokumentu i zbudować / zatwierdzić nową wersję powiązaną z poprzednią. Uzasadniony.

  • Ma konkretny zaakceptowany powód, dla którego cały zespół ma zostać zaangażowany, a następnie jest uzasadniony, aby utrzymać go w repozytorium git. (Nie znamy Twojego kontekstu, Ty i Twój zespół znasz)

W każdym innym scenariuszu należy go bezpiecznie zignorować.

Jeśli jednak uzasadnione jest utrzymanie ich w repozytorium git, może to oznaczać kolejny większy problem, przed którym stoi Twój zespół. (Brak systemu CI lub podobnych, okropnych problemów z wydajnością, grożący przestój podczas budowy itp.)

throawableAccount2892391
źródło
1

Zgodnie z zasadą kontroli wersji tylko „obiekty podstawowe” powinny być przechowywane w repozytorium, a nie „obiekty pochodne”.

Istnieją wyjątki od reguły: mianowicie, gdy istnieją konsumenci repozytorium, którzy wymagają obiektów pochodnych i oczekuje się, że nie będą mieli wymaganych narzędzi do ich wygenerowania. Inne rozważania mają znaczenie, na przykład czy ilość materiału jest niewygodna? (Czy byłoby lepiej, gdyby w projekcie wszyscy użytkownicy mieli te narzędzia?)

Skrajnym przykładem tego jest projekt, który implementuje rzadki język programowania, którego kompilator jest napisany w tym samym języku (dobrze znane przykłady obejmują Ocaml lub Haskell). Jeśli w repozytorium znajduje się tylko kod źródłowy kompilatora, nikt go nie zbuduje; nie mają skompilowanej wersji kompilatora, którą mogliby uruchomić na maszynie wirtualnej, aby mogli skompilować kod źródłowy tego kompilatora. Co więcej, najnowsze funkcje tego języka są natychmiast używane w samym źródle kompilatora, więc do jego zbudowania zawsze wymagana jest najnowsza wersja kompilatora: miesięczny plik wykonywalny kompilatora uzyskany osobno nie skompiluje bieżącego kodu, ponieważ kod korzysta z funkcji językowych, które nie istniały miesiąc temu. W tej sytuacji skompilowana wersja kompilatora prawie na pewno musi zostać sprawdzona w repozytorium i zaktualizowana.

Kaz
źródło