La documentazione generata deve essere archiviata in un repository Git?

Quando usi strumenti come jsdocs , genera file HTML statici e i suoi stili nella base di codice in base ai commenti nel codice.

Questi file dovrebbero essere archiviati nel repository Git o dovrebbero essere ignorati con .gitignore?

In assenza di esigenze specifiche, non è possibile archiviare qualsiasi file che può essere creato, ricreato, creato o generato da strumenti di compilazione utilizzando altri file sottoposti a controllo della versione. Quando è necessario, può essere (ri) creato dall'altro fonti (e normalmente sarebbero un aspetto del processo di compilazione).

Quindi quei file dovrebbero essere ignorati con .gitignore.

La mia regola è che quando clonare un repository e premo un pulsante "build", poi, dopo un po ', tutto viene creato. Per ottenere ciò per la tua documentazione generata, hai due scelte: o qualcuno è responsabile della creazione di questi documenti e della loro messa in git, oppure documenti esattamente quale software mi serve sulla mia macchina di sviluppo e ti assicuri che premendo il tasto "build" pulsante crea tutta la documentazione sulla mia macchina.

Nel caso della documentazione generata, in cui qualsiasi singola modifica apportata a un file di intestazione dovrebbe modificare la documentazione, è meglio farlo sulla macchina di ogni sviluppatore, perché voglio sempre la documentazione corretta, non solo quando qualcuno l'ha aggiornata. Ci sono altre situazioni in cui la generazione di qualcosa potrebbe richiedere molto tempo, complicata, richiedere software per il quale si dispone di una sola licenza, ecc. In tal caso, dare a una persona la responsabilità di mettere le cose in git è meglio.

@Curt Simpson: avere tutti i requisiti software documentati è molto meglio di quanto abbia mai visto in molti posti.

Questi file non devono essere archiviati perché i dati per generarli sono già presenti. Non si desidera memorizzare i dati due volte (DRY).

Se hai un sistema CI, potresti forse creare quel documento e archiviarlo per quel build / pubblicarlo su un server web.

Un vantaggio di averli in alcuni repository (uguali o diversi, preferibilmente generati automaticamente) è che puoi vedere tutte le modifiche alla documentazione. A volte queste differenze sono più facili da leggere rispetto alle differenze al codice sorgente (in particolare se ti interessano solo le modifiche alle specifiche, non l'implementazione).

Ma nella maggior parte dei casi non è necessario averli nel controllo del codice sorgente, come spiegato nelle altre risposte.

Ignorato. Ti consigliamo di far sì che gli utenti del repository siano in grado di ricostruirli comunque, eliminando la complessità di essere sicuri che i documenti siano sempre sincronizzati. Non c'è motivo di non avere i manufatti raccolti in un unico posto se si desidera avere tutto in un posto e non è necessario costruire nulla. Tuttavia i repository di origine non sono davvero un buon posto per farlo, anche se la complessità fa più male della maggior parte dei luoghi.

Dipende dal processo di distribuzione. Ma il commit di file generati in un repository è un'eccezione e, se possibile, dovrebbe essere evitato. Se puoi rispondere a entrambe le seguenti domande con Sì , il check-in nei tuoi documenti potrebbe essere un'opzione valida:

• I documenti sono un requisito per la produzione?
• Il tuo sistema di distribuzione non dispone degli strumenti necessari per creare i documenti?

Se queste condizioni sono vere, probabilmente si sta eseguendo la distribuzione con un sistema legacy o un sistema con vincoli di sicurezza speciali. In alternativa, è possibile eseguire il commit dei file generati in un ramo di rilascio e mantenere pulito il ramo principale.

Dipende. Se quei documenti:

• Deve essere parte del repository, come il readme.md, quindi è preferibile tenerli nel repository git. Perché può essere complicato gestire tali situazioni in modo automatizzato.

• Se non hai un modo automatizzato per costruirli e aggiornarli, come un sistema CI, ed è destinato a essere visto per il pubblico in generale, è preferibile tenerli nel repository git.

• Richiede MOLTO tempo per costruirli, quindi è giustificabile mantenerli.

• Sono pensati per essere visti per il pubblico generale (come il manuale dell'utente) e ci vuole molto tempo per costruirlo, mentre i tuoi documenti precedenti diventano inaccessibili (offline), quindi è giustificabile tenerli nel repository git.

• Sono pensati per essere visti per il pubblico in generale e devono mostrare una storia dei suoi cambiamenti / evoluzione, potrebbe essere più facile mantenere impegnate le versioni precedenti dei documenti e costruire / impegnare quella nuova collegata alla precedente. Giustificabile.

• Ha un motivo specifico accettato per il commit di tutta la squadra, quindi è giustificabile tenerli nel repository git. (Non conosciamo il tuo contesto, tu e il tuo team lo sapete)

In qualsiasi altro scenario, dovrebbe essere tranquillamente ignorato.

Tuttavia, se è giustificabile tenerli nel repository git, potrebbe essere un segno di un altro problema più grande che la tua squadra sta affrontando. (Non avere un sistema CI o simili, orribili problemi di prestazioni, affrontare i tempi di fermo durante la costruzione, ecc.)

Come principio di controllo della versione, solo "oggetti primari" dovrebbero essere archiviati in un repository, non "oggetti derivati".

Ci sono eccezioni alla regola: vale a dire, quando ci sono consumatori del repository che richiedono gli oggetti derivati ​​e ci si aspetta ragionevolmente che non dispongano degli strumenti necessari per generarli. Altre considerazioni pesano, come è la quantità di materiale ingombrante? (Sarebbe meglio per il progetto far sì che tutti gli utenti avessero gli strumenti?)

Un esempio estremo di questo è un progetto che implementa un raro linguaggio di programmazione il cui compilatore è scritto in quel linguaggio stesso (esempi ben noti includono Ocaml o Haskell). Se nel repository è presente solo il codice sorgente del compilatore, nessuno può crearlo; non hanno una versione compilata del compilatore che possono essere eseguiti sulla macchina virtuale, in modo che possano compilare il codice sorgente di quel compilatore. Inoltre, le ultime funzionalità del linguaggio vengono immediatamente utilizzate nell'origine del compilatore stesso, in modo che per compilarlo sia sempre necessario avvicinarsi all'ultima versione del compilatore: un eseguibile del compilatore di un mese ottenuto separatamente non compilerà il codice corrente perché il codice utilizza funzionalità linguistiche che non esistevano un mese fa. In questa situazione, la versione compilata del compilatore deve quasi sicuramente essere controllata nel repository e mantenuta aggiornata.