Jakie dokumenty powinny być przechowywane w kontroli wersji i jak powinny być przechowywane?

Question

Znalazłem kilka podobnych pytań (here, here i here) z prośbą o przechowywanie dokumentów w kontroli wersji. Mam bardziej szczegółowy wymóg i ogólne pytanie. Konkretnym wymaganiem jest to, że chcę używać Git. Bardziej ogólne pytanie brzmi: w jaki sposób dokumenty (dotyczące projektu, testu, ogólnych praktyk, wskazówek itd.) Powinny być przechowywane w Git? Mówiąc szerzej, jakie dokumenty powinny być przechowywane?

mogę myśleć kilka sposobów:

1. Word/dokumentów Open Office. Nowy Office Word ma format docx, który zamienia dokumenty, ale ma również rozpakowany format XML, który może być użyty do wydajnego przechowywania różnic w Git. Funkcja diff jest nadal uszkodzona, ponieważ XML są zgniecione w jednej linii. To nie jest lepsze niż przechowywanie pliku binarnego w Git.
2. Wiki. Jakie istnieją rozproszone wiki? Byłoby to jak coś w rodzaju Latex, gdzie dokumenty są zapisywane i kompilowane/przeglądane jako wiki.
3. Lateks - ale używając go do dokumentów, uważam go za całkiem nieodpowiedni dla dokumentów. Czy istnieje odpowiednik dokumentacji? (W jaki sposób tworzone są strony podręcznika?)
4. Zwykłe formaty tekstu, ale brakuje tego z powodu braku diagramów, które przywołują inny punkt.

W jaki sposób zapisywać wizualizacje? W czym w ogóle powinni się ułożyć? Pracuję w środowisku Linux, ale inni uczestnicy projektu są w systemie Windows. Jakie jest rozwiązanie wieloplatformowe, które przypomina Visio? I oczywiście nie powinno tworzyć plików binarnych, które mają być przechowywane w Git. Jak to się wtedy wiąże z dokumentacją? (Np. Podobnie jak Latex może odwoływać się do innych diagramów po kompilacji.)

Answer 1

Git obsługuje pliki binarne tak samo dobrze jak pliki tekstowe. Zamiast jawnie zapisywać różnice, Git przechowuje całe poprzednie wersje plików w repozytorium. Obiekty repozytorium są następnie kompresowane, aby zaoszczędzić miejsce. Diffy są rekonstruowane w locie za każdym razem, gdy o nie poprosisz.

Biorąc pod uwagę tylko przestrzeń dyskową, nie ma dużej różnicy między przechowywaniem dokumentu XML Office nieskompresowanego w Git i przechowywanie spakowanej wersji tego samego dokumentu. Jedyna różnica polegałaby na względnej wydajności Zip w zależności od tego, jaką kompresję Git wybierze.

Answer 2

Dla dokumentów Word, spróbuj użyć RTF (format RTF), który jest w zasadzie tekstem. Inną możliwością jest HTML. Są tekstem, więc powinieneś umieć je porównywać.

Większość Wiki jest rozprowadzana, ponieważ są przeznaczone do współpracy. Myślę, że naprawdę pytasz o to, czy istnieją hostowane rozwiązania, czy też musisz nimi zarządzać. Spójrz na http://www.atlassian.com/.

Answer 3

Większość formatów dokumentów nie gra zbyt dobrze z kontrolą źródła. Prawie wszystko, co wymienisz, jest albo binarnym, albo zwiniętym znacznikiem, który nie będzie się różnił. Tak długo, jak chcesz tylko wersji dokumentów i nie przejmuj się różnicami, używaj dowolnego formatu, który ci się podoba. Wolę dokumenty Microsoft Word, ponieważ można używać wbudowanego systemu śledzenia zmian i komentarzy do śledzenia delt między dokumentami.

Jeśli chodzi o dokumenty, które przechowujesz, to polecam przechowywanie wszystkiego, z czego będziesz mógł korzystać na później. Jakie dokumenty może ktoś wykorzystać do kontynuowania projektu, jeśli odejdziesz? Jakie dokumenty byłyby pomocne w doprowadzeniu nowej osoby do prędkości?Oznacza to specyfikacje, ale nie dokumenty, takie jak tabele pożegnalne.

Aby odpowiedzieć na część wiki swojego pytania, sprawdź numer DokuWiki. Przechowuje wszystko w plikach tekstowych, dzięki czemu można je bardzo łatwo dodać do systemu kontroli źródła.

Answer 4

Po prostu żyłem z tym, że nie mogę śledzić zmian w formatach plików binarnych za pomocą systemu kontroli wersji, ale używam go tak czy inaczej, ponieważ jest to przydatne. Zauważ, że zazwyczaj większość tego typu plików to produkty robocze, które zostaną wydane (podręczniki użytkownika, dokumenty itp.).

W przypadku wczesnych artefaktów projektów, takich jak wymagania i projekty początkowe, używam dokumentów tekstowych - nie dlatego, że mogę śledzić zmiany, ale ponieważ lubię używać mojego IDE do tego.

Nigdy tak naprawdę nie zostałem "ugryziony" przez fakt, że zmiana nie może być "zmieniona" w kontroli wersji. Komentarze do commitów i inne wytyczne dotyczące dokumentacji, dotyczące zmiany ważnego dokumentu binarnego zwykle stanowią uzupełnienie tego braku widoczności - w tym przypadku istnieje inna ścieżka, jeśli jej szukasz.

Zgadzam się, że to nie jest idealne, ale nie sądzę, że naprawdę warto się martwić.

Być może właśnie przyzwyczaiłem się do idei zbioru plików, które mógłbym śledzić tak bardzo, jak bym chciał.

Dużo wkładam w kontrolę wersji, ale także śledzę defekty w przypadku niektórych rzeczy, których długość życia jest tymczasowa.

Answer 5

Moja firma przechowuje dokumenty Word w SVN i uzyskuje do nich dostęp za pośrednictwem TortoiseSVN.

Żółw wykorzystuje wbudowaną funkcję śledzenia zmian programu Word, aby pokazać "różnicę" dwóch wersji.

Działa to naprawdę dobrze, ale wymaga systemu Windows i programu Word.

Edit:

Można chyba dostać tę pracę z Git zbyt. Jeśli zainstalujesz TortoiseSVN, spójrz na %PROGRAMFILES%\TortoiseSVN\Diff-Scripts\, zobaczysz, co robi żółw.

Jeśli używasz git zakładam, że jesteś wystarczająco 1337 do włamywanie go do pracy dla Ciebie :)

Answer 6

Przy podejmowaniu decyzji, co wybrać format dokumentu, należy upewnić się, że członkowie zespołu (lub jesteś działa sam?) są wygodne w pracy z samym formatem.

1. Pamięć masowa to nie problem, ponieważ można zobaczyć różnice między wersjami i scalaniem. Z mojego doświadczenia wynika, że ​​nic nie pobije formatów tekstowych, które można dowolnie edytować w dowolnym edytorze tekstów. Nie dotyczy to HTML i żadnego formatu opartego na XML. DocBook jest ledwie użytecznym wyjątkiem.

2. Dobrym wiki, które może używać dowolnego z popularnych systemów kontroli wersji i być skonfigurowane w sposób rozproszony jest IkiWiki. W IkiWiki parsowanie znaczników odbywa się w wtyczkach, więc możesz wybrać format wejściowy na podstawie dokumentu. "Domyślne", Markdown jest bardzo zbliżone do formatów tekstowych.

3. Jeśli nie jesteś zadowolony z używania LaTeX, nie używaj go. Myślę, że nie nadaje się do robienia szybkich notatek. Strony man są napisane w nroff, ale wiele osób używa innych formatów, takich jak POD.

Niektóre projekty, które starają się być alternatywą dla Visio to Kivio (KDE) i Dia (Gtk/Gnome). Nie używałem samego Visio, więc nie mogę komentować ich zestawów funkcji. Prawdopodobnie zależy to od tego, jakiego rodzaju wizualizacje/diagramy chcesz stworzyć. UML? Wykresy przepływu?

Answer 7

Dla OOO, dokumentów Word i innych plików binarnych, należy spojrzeć na pro-git http://git-scm.com/book/ch7-2.html