Czy wygenerowana dokumentacja powinna być przechowywana w repozytorium Git?

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?

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.

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.

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.

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.

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.

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.

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

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.