Git dovrebbe essere usato per la documentazione e la gestione dei progetti? Il codice dovrebbe essere in un repository separato?

68

Sto avviando un repository Git per un progetto di gruppo. Ha senso archiviare i documenti nello stesso repository Git del codice - sembra che questo sia in conflitto con la natura del flusso di revisione git.

Ecco un riassunto delle mie domande:

Lo stile di revisione di Git sarà confuso se sia il codice che i documenti sono controllati nello stesso repository ? Esperienze con questo?
Git è adatto per il controllo di revisione della documentazione?
NON sto chiedendo se un sistema di controllo delle revisioni in generale dovrebbe o non debba essere usato per la documentazione - dovrebbe.

Grazie per il feedback finora!

git version-control project-management

— EmpireJones
fonte

Ah, va bene ... grazie per il chiarimento. Non vedo perché sarebbe un problema, ma non ho alcuna esperienza personale con GIT (solo una comprensione teorica), quindi lascerò che qualcuno con esperienza più diretta risponda a questa domanda.

— Flimzy,

1

Non vedo bene come questo sia sull'argomento. Stai parlando di documentazione software e impegno con un DVCS

— Tim Post

Probabilmente dipende dalla documentazione e dalle tue esigenze. Hai bisogno di diff ed è in un formato in grado di gestirlo? Se git fornisce sicuramente i servizi richiesti. Batte con un sistema di gestione dei documenti separato ...

— Rig

Se la tua documentazione è in chiaro - va bene. Se si tratta di un formato binario, in sostanza è necessario un sistema di controllo della versione che comprenda il formato binario: si tratta del blocco del fornitore nella sua forma più pura.

correlati: Quale parte del progetto dovrebbe essere nel controllo del codice sorgente?

— moscerino del

53

Conserviamo la documentazione in SVN per tutto il tempo. In effetti, l'intero manuale dell'utente è scritto in LaTeX e memorizzato in SVN. Abbiamo scelto LaTeX specificatamente perché è un linguaggio testuale e facile da mostrare differenze riga per riga.

Archiviamo anche alcuni file in formato non testuale, come file .doc di Microsoft Office, fogli di calcolo, file .zip, ecc., Se necessario ... ma alcuni dei vantaggi di un RCS vengono persi quando non riesci a vedere il valore incrementale diff.

La chiave è davvero assicurarsi che la documentazione sia ben organizzata, in modo che le persone possano trovare (e aggiornare) la documentazione (e la fonte) quando ne hanno bisogno.

— flimzy
fonte

11

Se sei un negozio Microsoft, TortoiseSVN supporta le differenze riga per riga di MS Office.

— Phil

2

Eliminare i formati di documenti binari renderebbe il mondo un posto migliore. o dato che i documenti sono in chiaro, non dovrebbe esserci alcun problema reale con un DVCS.

— Kai Inkinen,

Oh, e la prima volta che ho sentito parlare di TortoiseSVN e dei file doc, quindi +1 per quello. Mi chiedo se questo finirà su Tortoise [AnyDVCS] in qualsiasi momento in futuro.

— Kai Inkinen,

@Phil: In che modo TortoiseSVN riesce a farlo? Il visualizzatore di documenti diff è integrato con il client SVN o può essere utilizzato in modo indipendente?

— Flimzy,

1

Un'opzione interessante sarebbe quella di utilizzare Pandoc in modo che la maggior parte della documentazione sia in Markdown, ma i bit cruciali possono ancora usare TeX. Dal momento che compila Markdown in LaTeX, i risultati sembrano uguali. Tuttavia, ciò consentirebbe anche di esportarlo in diversi formati e renderebbe più semplice la lettura della fonte.

— Tikhon Jelvis,

22

Bene dipende da quale formato usi per la documentazione. Se è basato sul testo, va tutto bene.

Git può anche archiviare contenuti binari e puoi tenere traccia delle revisioni, ma l'output diff non avrà senso.

È anche possibile memorizzare la documentazione nel codice stesso come perldoc pod, java ha anche un formato / annotazione per questo.

— cstamas
fonte

Sono d'accordo, mentre è possibile archiviare documentazione non testuale, git farà molto meglio se si memorizza invece testo. Si è parlato di un driver diff che sa

— diffondere

Pensavo che Word avesse spostato il loro formato dal binario all'XML.

— cledoux,

3

@ karategeek6 Il formato 'XML' di Word non è leggibile dall'uomo. E una riga di testo non corrisponde a una riga dell'XML di Word, anche in approssimazione. Quindi potrebbe anche essere binario.

È possibile indicare a Word di salvare l'output in XML non compresso. Scegli Save As, quindi seleziona Word XML Document (*.xml)anziché l'impostazione predefinita Word Document (*.docx). L'XML è piuttosto complesso, quindi non è garantito che le modifiche siano facilmente leggibili, ma almeno non saranno binarie.

— Kyralessa,

> ma l'uscita diff non avrà senso. In caso di diff, potremmo aprire 2 revisioni di un documento fianco a fianco e confrontarle con i nostri occhi :)

— Luca

14

Non riesco a immaginare perché pensi che potrebbe esserci un problema usando git, o qualsiasi altro sistema di controllo della versione, per la documentazione. Proprio come il codice sorgente, la documentazione dovrebbe avere una cronologia completa e la possibilità di tornare a una versione precedente se necessario. Un sistema di controllo della versione è perfetto per questo.

6

Solo se la documentazione è in forma di testo. I BLOB binari non beneficiano completamente del controllo della versione.

2

@ ThorbjørnRavnAndersen: Anche così, a meno che tu non abbia un sistema di versioning specifico per i binari, probabilmente è meglio mantenere persino i file binari in Git piuttosto che da soli.

— Tikhon Jelvis,

@TikhonJelvis Non mi sono chiesto se è una buona idea mettere i file binari in git - se sono i manufatti originali, lo è. Prova, tuttavia, a eseguire "git diff" sui documenti di Word.

@ user1249: potresti "esportare" la revisione 2 sul desktop, dire my_docs_rev15.docx e my_docs_rev14.docx quindi aprirlo fianco a fianco e confrontarli con gli occhi e il cervello, non è così difficile :)

— Luca

14

È chiaro che l'utilizzo di un qualche tipo di sistema di controllo versione per l'archiviazione di documenti è un nobrainer. La parte più interessante della domanda è se è una buona idea archiviare i documenti nella stessa posizione come codice sorgente? Il possibile problema qui è che potrebbe essere difficile impostare privilegi di accesso diversi per codice e documentazione in quel caso. E in molti casi aziendali le persone avranno bisogno di accedere ai documenti ma non al codice sorgente, come i dipartimenti marketing o BA.

— Ma99uS
fonte

3

Sì, l'aspetto "stessa posizione" è una delle parti chiave di questa domanda!

La stessa posizione è buona se riesci a gestirla, perché evita la necessità di avere conoscenze tribali (sapere dove cercare), o la necessità di andare a cercare dove sono le cose.

— quick_now

Potrebbero non aver bisogno dell'accesso al codice, ma non dovrebbe far loro male avere quell'accesso. Non devono guardarlo. I segreti generalmente non dovrebbero comunque essere nel controllo della versione.

— bdsl,

9

Nell'azienda che lavoro inseriamo la documentazione in SVN. Tuttavia, dopo alcuni conflitti e la necessità di condividerlo, abbiamo deciso di spostarlo su Mediawiki.

Inizialmente era trac, dopodiché si è trasferito su Mediawiki perché era più facile da usare ...

Il problema principale con SVN era la causa della condivisione che avevamo un sistema di autorizzazione per SVN.

— confiq
fonte

2

Non intendi Mediawiki, il motore wiki che utilizza Wikipedia?

@Martijn, lo presumo così

— Teo Klestrup Röijezon,

@Martijn: Sì, modificato

— confiq

Preferirei attenermi a un wiki piuttosto che inviare molti file che non sono ovviamente destinati a un SCM, ma questo ha più a che fare con le preferenze personali. Puoi fare molto di più. Mi piace particolarmente Foswiki e il loro modello basato su sito Web / progetto. Sono contento che qualcuno abbia deciso di usare un wiki a causa di problemi :) +1.

— Oeufcoque Penteano,

9

Avere più di un semplice codice sorgente in un repository è un'ottima cosa.

Raggruppa tutte le risorse e trasforma il progetto in un'entità coesiva e centralizzata anziché in una raccolta sparsa di file. Collaboratori / dipendenti sanno dove trovare tutto, anziché inviare "Dove posso cambiare la documentazione per la funzione x?" messaggi di posta elettronica.

Ti consigliamo di organizzare le cose. Avere un sistema per separare il srcda il imagesda docs. È sempre possibile aggiungere a .gitignorea una directory per mantenere puliti il repository e la cronologia. Poiché i commit di Git sono basati su file, * è possibile disaccoppiare le modifiche di origine dalle modifiche alla documentazione nel modo desiderato.
Come altri hanno già detto, Git è ottimo per il versioning della documentazione purché sia basato su testo.
Sono completamente d'accordo; la documentazione deve essere aggiornata accanto al codice.

La mia credibilità deriva dall'essere un utente GitHub e dal contribuire a un progetto ed esplorarne molti altri. Nella mia esperienza, un progetto completo e unificato è facile da dire da un progetto mancante. Cerco di contenere tutti i miei progetti all'interno di singole directory ogni volta che è possibile.

* Questo non è abbastanza accurato, perché ci sono modi per specificare parti di un file da impegnare ( ecco un esempio ).

— Tyler Wayne
fonte

4

Sono venuto qui con una domanda simile. Veniamo da un ambiente SVN, dove fondamentalmente è un gioco da ragazzi mantenere tutti i materiali relativi a un progetto nello stesso repository. A causa della natura di SVN, puoi facilmente controllare parti del repository, quindi se hai solo bisogno del codice sorgente (ad esempio una distribuzione del sito Web), non è un problema.

Con Git, le cose sono diverse. Un checkout è sempre a livello di root, quindi se vuoi mettere tutto nello stesso repository, finirai sempre con la stessa struttura di directory. Un approccio che ho incontrato è quello di mettere tutto in rami separati, cioè hai rami di codice (che normalmente sarebbero i tuoi normali rami master, sviluppo, ecc.) E un ramo doc, che ha una propria struttura di directory separata. Non sono ancora sicuro che sia l'idea migliore, ma è un suggerimento che elude il problema che immagino sia alla base della tua domanda.

— Eelke Blok
fonte

Rami diversi con strutture di directory radicalmente diverse hanno un pessimo odore di codice. Lascerei tutto in un unico repository, rendendo più semplice per i partecipanti l'aggiunta più semplice di un mix di codice e documentazione. In effetti, la programmazione alfabetica (Google that!) Lo richiede.

— martedì

Quando distribuisco i pacchetti, sono parziale allo stile .deb che mi consente di scaricare eseguibili su tutti i server, mentre la mia scatola di sviluppo ha anche i pacchetti di documentazione.

— martedì

1

Uso un wiki per documenti interni ... ottieni revisione PLUS accesso prominente / editing facile. Quando la documentazione non è sincronizzata, aggiornarla subito e lì. Per la documentazione per l'utente finale, prendere in considerazione uno strumento professionale come Madcap Flare Usano un dialetto XML per condividere, comporre e trasformare la documentazione.

— Michael Brown
fonte

-1

Nel codice, i pensieri sono in genere separati riga per riga. Tendo a scrivere documentazione con involucri di linee morbide. Quando eseguo il commit di questi file, le righe sono lunghe un intero paragrafo. Non è molto utile da leggere git diff. Questo è il problema che stavo cercando di risolvere quando ho cercato su Google questa pagina. Grazie ad Arne Hartherz per avermi fatto conoscere git diff --word-diff. Ti potrebbe piacere git diff --color-wordsanche meglio.

— tbc0
fonte