La cronologia di commit deve essere utilizzata per trasmettere informazioni importanti agli sviluppatori?

Durante una riunione riguardante il rollback di un SDK di terze parti dall'ultima versione, è stato notato che i nostri sviluppatori hanno già segnalato nella cronologia del commit che l'ultima versione non deve essere utilizzata.

Alcuni sviluppatori hanno sostenuto che si trattava di una cattiva pratica e che avrebbe dovuto invece essere annotata nel file di origine (ovvero // Don't upgrade SDK Version x.y.z, see ticket 1234) o in un READMEfile a livello di progetto . Altri hanno sostenuto che, poiché la cronologia del commit fa parte della documentazione del progetto, è un luogo accettabile per tali informazioni, dal momento che dovremmo comunque leggerle tutte.

La cronologia di commit dovrebbe essere utilizzata per trasmettere informazioni critiche ad altri sviluppatori o tali informazioni dovrebbero essere duplicate in un'altra posizione come un progetto READMEo commenti nel file sorgente pertinente?

Se avessi intenzione di esaminare l'aggiornamento a una versione più recente di un SDK di terze parti, l'ultimo posto che avrei cercato è nella storia del sistema di controllo del codice sorgente.

Se il tuo prodotto utilizza la versione 2.0 di un SDK e qualcuno è interessato all'aggiornamento a 3.0, non credo sia ragionevole pensare che dovrebbero guardare indietro nel tempo nel tuo sistema di controllo del codice sorgente per scoprire che non è una buona idea.

Qui abbiamo una wiki del team che ha una manciata di pagine con informazioni interessanti che ogni sviluppatore legge (convenzioni di codifica, come impostare un ambiente di sviluppo per costruire il prodotto, quali elementi di terze parti è necessario installare, ecc.). Questo è il tipo di posto che sarebbe appropriato per un avvertimento contro l'aggiornamento di una libreria di terze parti.

Dovrebbe essere notato nella cronologia del commit, ma il posto migliore in assoluto per mettere l'avviso è nello stesso posto in cui si definisce la dipendenza. Se ad esempio hai un file .pom maven che dichiara le tue dipendenze artefatto, farei qualcosa del tipo:

<!-- Do not change the SDK version because it causes Foo crashes. For more detail see Issue #123 -->

Direttamente sopra la <dependency>linea.

Il numero 123 includerà i dettagli su come si è arrestato, la versione aggiornata a quella che ha causato gli arresti anomali e probabilmente dovrebbe essere nuovamente aggiunto al backlog per essere rivisitato in seguito - è possibile che esista una versione ancora più nuova che risolva il problema. O modificando automaticamente il biglietto o manualmente, invierà un'e-mail al team per fargli conoscere il problema corrente ora, e trovandosi nel tracker consente alle persone di ritrovarlo più tardi.

Il motivo per inserirlo con la dichiarazione di dipendenza è perché chi vuole cambiare la versione la vedrà nel momento in cui vuole cambiarla e capire perché non dovrebbe.

Non vorrei commentare il codice sorgente perché posso facilmente immaginare una situazione in cui qualcuno esegue un controllo delle tue dipendenze e inizia ad aggiornarle. Non dovrebbero aver bisogno di scrutare la base di codice per ogni commento TODO per farlo.

Il collegamento al ticket di emissione consente a uno sviluppatore curioso di sapere come è fallito e potenzialmente rivederlo in un secondo momento. Senza quello, potrebbe diventare abbastanza statico e non essere mai più aggiornato.

Informazioni critiche e non intuitive dovrebbero essere documentate dove le persone guarderanno quando considerano le informazioni.

Per i team e i progetti a cui ho lavorato, commetterei il rollback con il commento sul perché la nuova versione non è riuscita. Aggiungerei una storia di backlog per riprovare l'aggiornamento se la nuova versione viene riparata. Vorrei aggiungere commenti al sistema di build / agli script di build a cui è collegata la libreria.

Il roll-back fornirà ai futuri sviluppatori un contesto quando esamineranno la storia del progetto. La storia del backlog mantiene la necessità di questo aggiornamento come parte attiva del progetto. I commenti del sistema di generazione sono esattamente dove dovranno essere apportate le modifiche quando la libreria verrà finalmente aggiornata.

Non lo commenterei nel codice e non lo aggiungerei a un file README. Gli sviluppatori che pensano di provare l'aggiornamento non esamineranno questi elementi. Se lo aggiungi lì, quando il problema con la libreria verrà risolto e verrà eseguito un aggiornamento, dovrai rimuoverlo. Questo passaggio viene spesso dimenticato: si traducono in note controproducenti per il progetto.

Se il tuo progetto ha una configurazione diversa o un flusso diverso, la tua risposta potrebbe essere diversa. Penso che la chiave sia mettere a posto le informazioni dove lo sviluppatore le vedrà quando fa il lavoro per l'aggiornamento. In questo modo, se non è il momento giusto per l'aggiornamento, lo sviluppatore lo vedrà e si fermerà, e quando sarà il momento lo sviluppatore lo vedrà e rimuoverà la nota in modo da non confondere i futuri sviluppatori.

Volevo prestare maggiore attenzione al commento di Matthew evidenziando la sua idea importante in una risposta. C'è un motivo per cui non si desidera aggiornare l'SDK e tale motivo deve essere acquisito in un test di unità. Non un controllo per un numero di revisione, ma l'effettivo motivo sottostante.

Ad esempio, supponiamo che ci sia un bug nella nuova versione. Scrivi un unit test che verifica la presenza di quel bug. Se in seguito risolvono quel bug nell'SDK, l'aggiornamento avverrà senza intoppi. Se si verifica una modifica dell'API incompatibile, scrivere un test per verificare che il codice supporti la nuova API o che l'SDK supporti la vecchia API. È più un test di integrazione che un test unitario, ma dovrebbe essere comunque fattibile.

La mia azienda genera oltre 50 commit al giorno e non siamo esattamente grandi. Anche se ogni sviluppatore legge ogni singolo messaggio di commit, il che, francamente, non lo fa, l'intero motivo per cui abbiamo bisogno di una cronologia di commit registrata è perché la gente non se lo ricorda. E le persone non tornano indietro e leggono la storia in seguito a meno che non ci sia un problema. E non hanno motivo di sospettare un problema su un aggiornamento che, per quanto sanno, non si è ancora verificato.

In ogni caso, invia un'e-mail per impedire la duplicazione del lavoro nel breve termine e annotala negli script di compilazione e in un README o errata. Tuttavia, soprattutto se il problema con la nuova versione è sottile e richiede tempo per la risoluzione dei problemi, è necessario un modo per renderlo ovvio. Ciò significa un test unitario.

Sto riformulando la domanda come "Devo comunicare informazioni critiche che scopro al resto del team solo tramite il messaggio di commit?" Perché penso che ciò renda evidente che no, non dovresti. Faccio di tutto per comunicare molto (è qualcosa che la maggior parte dei team di sviluppo, nella mia esperienza, deve impegnare attivamente) e certamente faccio tutto il possibile per evitare di creare insidie ​​o lasciarle mentire.

Se la catena di azioni che mi porta a una tale scoperta fosse innescata da un biglietto, aggiornerei il biglietto (e mi assicurerei che le persone che dovrebbero sapere che questo hanno visibilità), probabilmente lo menzionerei faccia a faccia (sperando di lasciare almeno qualcuno con un senso assillante che "Accidenti, penso che Damon abbia detto qualcosa sull'aggiornamento", e ovviamente lascerei un commento nel codice nel punto in cui l'SDK è stato incluso in modo che nessuno potesse aggiornare senza avere la possibilità di vederlo. Potrei vedere se potessi farlo anche da qualche parte sulla nostra wiki di sviluppo, anche se questo è fatto di più con un occhio verso i futuri assunti, non la squadra attuale.

Ci vogliono solo un paio di minuti in più rispetto al tempo probabilmente impiegato per incontrare e scoprire il problema. Certamente non deciderei uno dei pezzi meno utilizzati della nostra documentazione e non lo lascerei.

Dovrebbe essere nella cronologia di commit, ma non dovrebbe essere solo nella cronologia di commit, immagina per un momento di assumere un nuovo sviluppatore. Ti aspetti che il nuovo sviluppatore legga tutti i messaggi di commit negli ultimi 10 anni del tuo progetto perché un paio di essi saranno fondamentali per comprendere la tua base di codice?

Secondo, dire che la situazione, ma non le modifiche al codice, eseguirai i commit della "documentazione" in modo da poter aggiungere messaggi di commit sulla falsariga di "il messaggio di commit dalla revisione 5432 è ora errato, ecco la situazione attuale".

Non sono sicuro di come comunichi il tuo team, ma credo che il modo più efficace per dirlo sia quello di inviare prima e-mail al gruppo e-mail del team, contrassegnato come "URGENTE" con il corpo che dice

Ragazzi, non possiamo usare SDK v xyz perché provoca l'overflow del buffer Foo e il servizio Bar si arresterà in modo anomalo. Stick con la versione xyy

Questo è quello che abbiamo fatto qui ed è il modo più affidabile per diffondere il messaggio. Se vuoi davvero essere pignolo (e se il tuo sistema di posta elettronica lo consente), richiedi una "conferma di lettura" sull'e-mail.

Una volta che hai detto all'intero team, una documentazione più dettagliata dovrebbe essere inserita in un wiki del team. Questo varierà, a seconda di come strutturi la tua documentazione. Se hai una sezione specifica per le dipendenze e i requisiti delle tue applicazioni, sarebbe un buon posto per aggiungerla.

Un ulteriore posto per documentare questo tipo di problema potrebbe essere nel codice sorgente stesso, sebbene ciò non sempre funzioni. Se si SDK version ...fa riferimento solo in uno o due punti ovvi, è possibile includere una nota sul non aggiornamento.

La cronologia dei file nel controllo del codice sorgente può essere molto lunga e, a seconda degli sviluppatori, potrebbe contenere più voci al giorno. Qualcuno che è stato in vacanza per una settimana potrebbe non avere il tempo di leggere la storia di commit di una settimana. Il file README è un posto migliore in quanto è un po 'più centrale e le persone potrebbero essere più inclini a leggerlo, ma non puoi assicurarti che tutti leggano effettivamente il README. Beh, suppongo che potrebbero se vedessero che è stato cambiato ...

Qualcosa del genere avrebbe dovuto essere inserito nei commenti di commit, ma trarrebbe beneficio anche dall'essere in altri posti.

Chiunque prenda la decisione di aggiornare, deve avere i fatti. Quella persona potrebbe non vivere nel controllo del codice sorgente. Cosa succederebbe se qualcuno leggesse questo problema su SO e non lo inserisse mai nella base di codice?

Ci deve essere una sorta di documento su questo SDK di terze parti.

• Che problema risolve?
• Perché è stato scelto questo particolare?
• Quali considerazioni devono essere fatte per quanto riguarda: versioni, aggiornamenti, test, ecc.
• Chi prende questa decisione?

Hai un caso in cui qualcosa del genere si è fatto strada nel controllo della versione e dovresti raccomandare a tutti di usare queste informazioni il più possibile. Solo il tuo team può decidere dove qualcuno eseguirà una ricerca in qualsiasi documentazione, controllo del codice sorgente o bug tracker per ottenere quante più informazioni possibili sull'argomento. Altrimenti, ti dimenticherai, qualcuno lo farà comunque, e sarai fortunato se fa jogging la memoria di qualcuno e lo riavvia rapidamente.

La storia è un ottimo posto per mettere i dati destinati a un lettore che lo sta consapevolmente cercando e ha un senso generale di dove dovrebbe essere. È un pessimo posto per mettere dati che devono essere offerti a un utente, piuttosto che cercati.

Le storie sono corpi molto grandi di testo relativamente non ordinato. Di solito hanno lo scopo di fornire allo sviluppatore informazioni dettagliate su cosa è cambiato e perché è stato cambiato. Questo può essere un sovraccarico di informazioni a meno che non si sappia cosa stanno cercando.

Se un utente non sa cosa sta cercando, le informazioni vengono rapidamente sepolte sotto centinaia di registri di commit e non hanno strumenti per eliminare la pila di informazioni di fronte a loro.

Interpreto questa situazione come se avesse due problemi di base, forse tre.

• Un aggiornamento SDK indesiderato è arrivato alla fonte, dove potrebbe influire negativamente sul prodotto.
• Dalla domanda: il contributore che ha eseguito l'aggiornamento indesiderato non era a conoscenza di una precedente decisione specifica di non aggiornare.

Il primo di questi, secondo me, è il più serio. Se un aggiornamento SDK indesiderato può farcela nel codice, lo stesso vale per altri problemi.

Qualcuno ha suggerito di aggiungere un caso di test unitario che fallirà se rileverà l'aggiornamento. Mentre impedirebbe il verificarsi dell'aggiornamento, credo che questo sia un percorso pericoloso, che porta al flusso di lava nel tempo. Sembra inevitabile che ad un certo punto in futuro l'SDK verrà aggiornato, per introdurre nuove funzionalità o correzioni di bug o perché la vecchia versione non è più supportata. Immagina i graffi alla testa, forse anche gli argomenti, che si verificheranno quando un tale test unitario fallisce.

Penso che la soluzione più generale sia quella di adeguare il processo di sviluppo. Per git, usa il processo di richiesta pull . Per Subversion e strumenti precedenti, usa branch e diff. Esistono però alcuni processi che consentono agli sviluppatori senior di rilevare questo tipo di problemi prima che entrino nella base di codice e influenzino altri sviluppatori.

Se il processo di richiesta pull fosse stato utilizzato nella tua situazione e se ogni richiesta pull fosse stretta e specifica, non sarebbe stato perso molto tempo. Una richiesta pull per l'aggiornamento dell'SDK sarebbe stata inviata e rifiutata con il commento che l'aggiornamento non è voluto. Nessun altro sarebbe stato influenzato e non sarebbe più necessario ripristinare l'aggiornamento dell'SDK.

Ma per rispondere direttamente alla domanda originale, concordo con gli altri sul fatto che aspettarsi che tutti gli sviluppatori leggano completamente l'intera cronologia delle revisioni del codice, note di rilascio, ecc. Per avvisi come questo è una perdita di tempo prezioso. Cosa c'è che non va nell'e-mail breve di una squadra?

Possibile terzo problema: perché l'aggiornamento non è voluto in primo luogo? Chiaramente almeno uno sviluppatore ha pensato che l'aggiornamento sarebbe stato positivo. Ci sono molte buone ragioni per ritardare un aggiornamento, ma anche molte cattive. Fai attenzione a evitare il flusso di lava (codice di retrocompatibilità non necessario) e il culto del carico ("non possiamo aggiornarlo, ma non so perché") anti-pattern!

Direi che aggiungere quel tipo di informazioni a una cronologia di commit è ok ma deve comunque essere documentato correttamente. Di recente abbiamo iniziato a utilizzare la confluenza (di atlassian). È ricercabile, è possibile impostare determinate pagine come preferite, ecc.

Alcuni altri strumenti potrebbero essere un blocco note pubblico in documenti evernote o google.

Espandendo la risposta di Karl, seguirei un approccio che impone automaticamente la restrizione come parte del processo di check-in stesso. Hai bisogno di qualcosa che non richiede alcuna azione proattiva per conto dello sviluppatore, come la lettura di un documento / wiki / README, e non può essere sovrascritto di nascosto.

Nella terra di controllo del codice sorgente TFS è possibile codificare politiche di check-in personalizzate che eseguono regole al momento del check-in. Ad esempio, è possibile definire un criterio che valuti la versione in un file di configurazione con un check-in in sospeso e non riuscirà se non è uguale a xyz Queste regole impediscono effettivamente allo sviluppatore di eseguire il check-in e possono fornire un messaggio descrittivo. Le politiche possono essere ignorate, ma è possibile generare avvisi quando ciò accade.

Un'alternativa potrebbe essere gated-checkins che falliranno con una qualche forma di unit test che valuta direttamente o indirettamente la versione dell'SDK, come menzionato da Karl.

Apprezzo che questa risposta sia molto incentrata su TFS, ma forse esistono funzioni simili nei sistemi di controllo versione / CI applicabili nella tua situazione (se non in TFS).