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!
git
version-control
project-management
EmpireJones
źródło
źródło
Odpowiedzi:
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ą.
źródło
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ę.
źródło
Save As
, a następnie wybierzWord XML Document (*.xml)
zamiast domyślnegoWord 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.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
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.
źródło
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.
źródło
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
src
od iimages
oddocs
. Zawsze możesz dodać a.gitignore
do 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 ).
źródło
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.
źródło
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.
źródło
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 zgit diff --word-diff
. Możesz polubićgit diff --color-words
jeszcze lepiej.źródło