Czy Git powinien być wykorzystywany do dokumentacji i zarządzania projektami? Czy kod powinien znajdować się w osobnym repozytorium?

68

Zaczynam repozytorium Git dla projektu grupowego. Czy sensowne jest przechowywanie dokumentów w tym samym repozytorium Git co kod - wygląda na to, że jest to sprzeczne z naturą przepływu wersji git.

Oto podsumowanie moich pytań:

  • Czy styl weryfikacji Gita będzie mylący, jeśli zarówno kod, jak i dokumenty zostaną sprawdzone w tym samym repozytorium ? Doświadczenia z tym?

  • Czy Git dobrze nadaje się do kontroli wersji dokumentacji?

  • Ja nie pytając, czy system kontroli wersji w ogóle powinny lub nie powinny być wykorzystywane do dokumentacji - powinno.

Dziękujemy za opinie do tej pory!

EmpireJones
źródło
Ach, ok ... dzięki za wyjaśnienie. Nie rozumiem, dlaczego byłby to problem, ale nie mam osobistego doświadczenia z GIT (tylko teoretyczne rozumienie), więc pozwolę komuś z bardziej bezpośrednim doświadczeniem odpowiedzieć na to pytanie.
Flimzy
1
Nie bardzo rozumiem, jak to jest w temacie. Mówisz o dokumentacji oprogramowania i zatwierdzaniu za pomocą DVCS
Tim Post
Prawdopodobnie zależy od dokumentacji i twoich potrzeb. Czy potrzebujesz różnic i czy jest w formacie, który może to obsłużyć? Jeśli git daje wymagane usługi na pewno. Uderza o oddzielny system zarządzania dokumentami ...
Rig
Jeśli twoja dokumentacja jest w postaci zwykłego tekstu - dobrze. Jeśli jest to format binarny, zasadniczo potrzebujesz systemu kontroli wersji, który rozumie format binarny - jest to blokada dostawcy w najczystszej postaci.

Odpowiedzi:

53

Przez cały czas przechowujemy dokumentację w SVN. W rzeczywistości cała nasza instrukcja obsługi jest napisana w LaTeX i zapisana w SVN. Wybraliśmy LaTeX specjalnie dlatego, że jest to język tekstowy i łatwo wyświetlać różnice między wierszami.

Przechowujemy również niektóre pliki w formacie innym niż tekst, takie jak pliki .doc pakietu Microsoft Office, arkusze kalkulacyjne, pliki .zip itp., Gdy jest to konieczne ... ale niektóre korzyści z RCS są tracone, gdy nie widać przyrostowego diffs.

Najważniejsze jest, aby upewnić się, że twoja dokumentacja jest dobrze zorganizowana, aby ludzie mogli znaleźć (i zaktualizować) dokumentację (i źródło), kiedy jej potrzebują.

Flimzy
źródło
11
Jeśli jesteś sklepem Microsoft, TortoiseSVN obsługuje MS Office diffs linia po linii.
Phil
2
Porzucenie binarnych formatów dokumentów uczyniłoby świat lepszym miejscem. o Biorąc pod uwagę, że dokumenty są zwykłym tekstem, nie powinno być też prawdziwego problemu z DVCS.
Kai Inkinen
Aha, i po raz pierwszy usłyszałem o TortoiseSVN i plikach doc, więc +1 za to. Zastanawiam się, czy to kiedyś skończy się na Tortoise [AnyDVCS].
Kai Inkinen
@Phil: Jak TortoiseSVN to osiąga? Czy przeglądarka doc-diff jest zintegrowana z klientem SVN, czy może być używana niezależnie?
Flimzy
1
Fajną opcją byłoby użycie Pandoc, aby większość dokumentacji była w Markdown, ale kluczowe bity mogą nadal korzystać z TeXa. Ponieważ kompiluje Markdown do LaTeX, wyniki wyglądają tak samo. Pozwoliłoby to jednak również na eksport do różnych formatów i ułatwiłoby odczytanie źródła.
Tikhon Jelvis
22

To zależy od tego, jakiego formatu używasz do dokumentacji. Jeśli jest to coś opartego na tekście, wszystko jest dobrze.

Git może również przechowywać zawartość binarną i możesz śledzić wersje, ale wyjście diff nie będzie miało sensu.

Możliwe jest również przechowywanie dokumentacji w samym kodzie, np. Perldoc pod, java również ma do tego jakiś format / adnotację.

cstamas
źródło
Zgadzam się, chociaż możliwe jest przechowywanie dokumentacji nietekstowej, git zrobi znacznie więcej, jeśli zamiast tego przechowujesz tekst. Mówiono o sterowniku różnic, który umie różnicować dokumenty ze słowami (lub podobnymi), ale nie jestem pewien, czy został on zaimplementowany, czy nie
Sverre Rabbelier,
Myślałem, że Word przeniósł swój format z binarnego na XML.
cledoux
3
@ karategeek6 Format „XML” programu Word nie jest czytelny dla człowieka. A jeden wiersz tekstu nie odpowiada jednemu wierszowi XML programu Word, nawet w przybliżeniu. Więc równie dobrze może być binarny.
Możesz poinstruować program Word, aby zapisał dane wyjściowe w nieskompresowanym pliku XML. Wybierz Save As, a następnie wybierz Word XML Document (*.xml)zamiast domyślnego Word Document (*.docx). XML jest dość złożony, więc nie ma gwarancji, że zmiany będą łatwe do odczytania, ale przynajmniej nie będą binarne.
Kyralessa,
> ale wyjście diff nie będzie miało sensu. W przypadku różnic możemy otworzyć 2 wersje dokumentu obok siebie i porównać na własne oczy :)
Luke
14

Nie mogę sobie wyobrazić, dlaczego uważasz, że może być problem z użyciem git lub jakiegokolwiek innego systemu kontroli wersji do dokumentacji. Dokumentacja, podobnie jak kod źródłowy, powinna mieć pełną historię i możliwość powrotu do wcześniejszej wersji, jeśli będzie to konieczne. System kontroli wersji jest do tego idealny.


źródło
6
Tylko jeśli dokumentacja jest w formie tekstowej. Binarne obiekty BLOB nie w pełni korzystają z kontroli wersji.
2
@ ThorbjørnRavnAndersen: Mimo to, o ile nie masz specyficznego dla binarnego systemu wersjonowania, prawdopodobnie lepiej jest przechowywać nawet pliki binarne w Git, niż na własną rękę.
Tikhon Jelvis
@TikhonJelvis Nie wątpiłem, czy dobrym pomysłem jest umieszczanie plików binarnych w git - jeśli są to oryginalne artefakty, tak jest. Spróbuj jednak uruchomić „git diff” na dokumentach Word.
@ user1249: możesz „wyeksportować” 2 wersję na pulpit, powiedzieć my_docs_rev15.docx i my_docs_rev14.docx, a następnie otworzyć ją obok siebie i porównać przez oczy i mózg, to nie jest takie trudne :)
Luke
14

Oczywiste jest, że używanie pewnego rodzaju systemu kontroli wersji do przechowywania dokumentów jest nobrainer. Bardziej interesującą częścią pytania jest to, czy dobrym pomysłem jest przechowywanie dokumentów w SAMEJ lokalizacji jako kodu źródłowego? Możliwym problemem jest to, że w takim przypadku może być trudno ustawić różne uprawnienia dostępu do kodu i dokumentacji. W wielu przypadkach biznesowych ludzie będą potrzebować dostępu do dokumentów, ale nie do kodu źródłowego, takiego jak dział marketingu lub licencjat.

Ma99uS
źródło
3
Tak, aspekt „ta sama lokalizacja” jest jedną z kluczowych części tego pytania!
Ta sama lokalizacja jest dobra, jeśli możesz nią zarządzać, ponieważ pozwala to uniknąć konieczności posiadania wiedzy plemiennej (wiedząc, gdzie szukać) lub konieczności szukania, gdzie jest ta rzecz.
szybko_nie
Mogą nie potrzebować dostępu do kodu, ale dostęp do niego nie powinien zaszkodzić. Nie muszą na to patrzeć. Sekrety na ogół i tak nie powinny podlegać kontroli wersji.
bdsl,
9

W firmie, w której pracuję, umieszczamy dokumentację w SVN. Jednak po kilku konfliktach i potrzebie podzielenia się nim postanowiliśmy przenieść go do Mediawiki.

Na początku był to trac, potem przeniósł się do Mediawiki, ponieważ łatwiej było używać ...

Głównym problemem związanym z SVN była przyczyna udostępniania, którą mieliśmy system autoryzacji SVN.

confiq
źródło
2
Nie masz na myśli Mediawiki, silnika wiki, którego używa Wikipedia?
@Martijn, zakładam, że tak
Teo Klestrup Röijezon
@Martijn: Tak, zredagowano
confiq
Wolę trzymać się wiki zamiast wysyłać wiele plików, które nie są oczywiście do SCM, ale to bardziej dotyczy osobistych preferencji. Można z tym zrobić znacznie więcej. Szczególnie podoba mi się Foswiki i ich szablon oparty na stronie internetowej / projekcie. Cieszę się, że ktoś wskazał na użycie wiki ze względu na problemy :) +1.
Oeufcoque Penteano
9
  • Posiadanie więcej niż tylko kodu źródłowego w repozytorium jest bardzo dobrą rzeczą.

    Grupuje wszystkie zasoby razem i zamienia projekt w spójny, scentralizowany byt, a nie rozproszony zbiór plików. Współpracownicy / pracownicy wiedzą, gdzie znaleźć wszystko, zamiast wysyłać „Gdzie zmienić dokumentację dla funkcji x?” e-maile.

    Będziesz chciał utrzymać porządek. Mieć system oddzielania srcod i imagesod docs. Zawsze możesz dodać a .gitignoredo katalogu, aby utrzymać repozytorium i historię w czystości. Ponieważ zatwierdzenia Git są oparte na plikach, * możesz oddzielić zmiany źródła od zmian w dokumentacji tak mocno, jak chcesz.

  • Jak powiedzieli inni, Git doskonale nadaje się do wersjonowania dokumentacji, o ile jest oparty na tekście.

  • Całkowicie się zgadzam; dokumentacja powinna być wersjonowana zaraz obok kodu.

Moja wiarygodność wynika z bycia użytkownikiem GitHub, z wkładu w jeden projekt i odkrywania wielu innych. Z mojego doświadczenia wynika, że ​​kompletny, zunifikowany projekt łatwo rozpoznać po częściowo brakującym. W miarę możliwości staram się przechowywać wszystkie moje projekty w pojedynczych katalogach.


* To nie jest całkiem dokładne, ponieważ istnieją sposoby na określenie części pliku do zatwierdzenia ( oto jeden przykład ).

Tyler Wayne
źródło
4

Przybyłem tutaj z podobnym pytaniem. Pochodzimy ze środowiska SVN, w którym zasadniczo nie ma nic przeciwko utrzymywaniu wszystkich materiałów związanych z projektem w tym samym repozytorium. Ze względu na naturę SVN możesz łatwo sprawdzić części repozytorium, więc jeśli potrzebujesz tylko kodu źródłowego (na przykład wdrożenia witryny internetowej), nie ma problemu.

W Git wszystko jest inne. Kasa jest zawsze na poziomie głównym, więc jeśli chcesz umieścić wszystko w tym samym repozytorium, zawsze skończysz z tą samą strukturą katalogów. Jednym z podejść, na jakie natrafiłem, jest umieszczenie wszystkiego w osobnych gałęziach, tj. Masz gałęzie kodu (które zwykle byłyby twoim normalnym gałęziami master, develop itp.) I gałąź doc, która ma swoją własną, oddzielną strukturę katalogów. Nie jestem jeszcze pewien, to najlepszy pomysł, ale jest to sugestia, która omija problem, który, jak sądzę, leży u podstaw twojego pytania.

Eelke Blok
źródło
Różne gałęzie z radykalnie różnymi strukturami katalogowymi mają dla mnie bardzo nieprzyjemny zapach. Pozostawiłbym to wszystko w jednym repozytorium, dzięki czemu autorzy mogą łatwiej dodawać kombinację kodu i dokumentacji. W rzeczywistości wymaga tego umiejętność programowania (Google, że!).
tbc0,
Podczas dystrybucji pakietów jestem częściowo zwolennikiem stylu .deb, który pozwala mi pobierać pliki wykonywalne na wszystkie serwery, podczas gdy moje okno programistyczne zawiera również pakiety dokumentacji.
tbc0,
1

Używam wiki do wewnętrznych dokumentów ... uzyskaj rewizję PLUS widoczny dostęp / łatwa edycja. Gdy dokumentacja nie jest zsynchronizowana, zaktualizuj ją natychmiast. W przypadku dokumentacji użytkownika końcowego rozważ profesjonalne narzędzie, takie jak Madcap Flare. Używają dialektu XML do udostępniania, komponowania i przekształcania dokumentacji.

Michael Brown
źródło
-1

W kodzie myśli są zwykle oddzielone linia po linii. Zwykle piszę dokumentację z miękkimi liniami. Kiedy zatwierdzam te pliki, linie mają cały akapit. Nie jest to zbyt przydatne do czytania git diff. To jest problem, który próbowałem rozwiązać, gdy przejrzałem Google i znalazłem tę stronę. Dzięki Arne Hartherz za zapoznanie mnie z git diff --word-diff. Możesz polubić git diff --color-wordsjeszcze lepiej.

tbc0
źródło