La cronologia dei commit dovrebbe essere utilizzata per trasmettere informazioni critiche agli sviluppatori?

Se dovessi esaminare l'aggiornamento a una versione più recente di un SDK di terze parti, l'ultimo posto che guarderei è nella cronologia del sistema di controllo del codice sorgente.

Se il tuo prodotto utilizza la versione 2.0 di un SDK e qualcuno è interessato all'aggiornamento alla 3.0, non penso sia ragionevole pensare che dovrebbero guardare indietro nel tempo nel tuo sistema di controllo del codice sorgente per scoprire che non è un 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 configurare 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 annotato nella cronologia dei commit ma il posto migliore in assoluto per mettere la notifica è nello stesso posto in cui si definisce la dipendenza. Se hai per esempio 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 tua <dependency> line.

Il numero 123 includerebbe dettagli su come si blocca, la versione che hai aggiornato causava il crash e probabilmente dovrebbe essere aggiunta nuovamente al tuo backlog per rivisitare in seguito - è possibile che ci sia ancora una versione più recente che risolve il problema. Automaticamente modificando il ticket o manualmente manualmente, invierà un'email al team per informarlo del problema corrente e, trovandosi nel tracker, consente alle persone di ritrovarlo in un secondo momento.

Il motivo per cui è stata messa la dichiarazione di dipendenza è perché chiunque voglia cambiare la versione la vedrà nel momento in cui vorrebbe cambiarla e capire perché non dovrebbe.

Non vorrei commentare nel codice sorgente perché posso facilmente immaginare una situazione in cui qualcuno esegue un controllo sulle dipendenze e inizia ad aggiornarle. Non dovrebbero aver bisogno di setacciare 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 di rivisitarlo in seguito. Senza quello, potrebbe diventare abbastanza statico e non essere mai aggiornato di nuovo.

Le informazioni critiche e non intuitive dovrebbero essere documentate dove le persone guarderanno quando prendono in considerazione le informazioni.

Per i team e i progetti su cui ho lavorato, avrei eseguito il rollback con il commento sul motivo per cui la nuova versione non è riuscita. Vorrei aggiungere una storia di backlog per provare nuovamente l'aggiornamento se la nuova versione viene risolta. Aggiungerei commenti al sistema di build / script di compilazione in cui è collegata la libreria.

Il roll-back fornirà agli sviluppatori futuri un contesto durante l'analisi della cronologia del progetto. La storia del backlog mantiene la necessità di questo aggiornamento come parte attiva del progetto. I commenti del sistema di compilazione sono giusti dove dovranno essere le modifiche al momento dell'aggiornamento definitivo della libreria.

Non lo commenterei nel codice e non lo aggiungerei a un README. Gli sviluppatori che pensano di provare l'aggiornamento non guarderanno a questi pezzi. Se lo si aggiunge lì, quando il problema con la libreria viene risolto e si esegue un aggiornamento, sarà necessario rimuoverlo. Questo passaggio viene spesso dimenticato: il risultato sono note che sono 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 le informazioni a posto se lo sviluppatore lo vedrà quando eseguirà il lavoro per l'aggiornamento. In questo modo, se il tempo non è giusto per l'aggiornamento, lo sviluppatore lo vedrà e si fermerà, e quando sarà il momento giusto lo sviluppatore lo vedrà e rimuoverà la nota in modo da non confondere gli sviluppatori futuri.

Volevo dare commento di Matteo maggiore attenzione evidenziando la sua idea importante in una risposta. C'è un motivo per cui non si desidera aggiornare il proprio SDK e tale motivo dovrebbe essere acquisito in un test unitario. Non un controllo per un numero di revisione, ma il motivo reale sottostante.

Ad esempio, diciamo che c'è un bug nella nuova versione. Scrivi un test unitario che controlli quel bug. Se in seguito risolveranno il problema nell'SDK, l'aggiornamento si verificherà senza intoppi. Se è presente una modifica API incompatibile, scrivi un test per verificare che il tuo codice supporti la nuova API o che l'SDK supporti la vecchia API. È più un test di integrazione che un test di unità, ma dovrebbe essere comunque fattibile.

La mia azienda genera oltre 50 commit al giorno e non siamo esattamente enormi. Anche se ogni sviluppatore legge ogni singolo messaggio di commit, che è sincero, non lo fa, l'intera ragione per cui abbiamo bisogno di una storia di commit registrata è perché la gente non può ricordarlo. E la gente non torna indietro e legge la storia più tardi a meno che non ci sia un problema. E non hanno motivo di sospettare un problema su un aggiornamento che, per quanto ne sappia, non si è ancora verificato.

In ogni caso, invia un'email per evitare la duplicazione del lavoro a breve termine, e annotalo negli script di compilazione e in un README o errata. Tuttavia, specialmente se il problema con la nuova versione è limitato e richiede molto tempo per risolvere i problemi, è necessario un modo per renderlo evidente. Ciò significa un test unitario.

Sto riformulando la domanda come "Devo comunicare informazioni critiche che scopro al resto del team solo tramite messaggio di commit?" Perché penso che sia ovvio che no, non dovresti. Cerco di comunicare molto (questo è qualcosa a cui la maggior parte dei team di sviluppo, nella mia esperienza, ha bisogno di impegnarsi attivamente) e io certamente faccio tutto il possibile per evitare di creare insidie o lasciarle mentire.

Se la catena di azioni che mi ha condotto a tale scoperta sono state attivate da un ticket, aggiornerei il ticket (e assicurarmi che le persone che dovrebbero sapere questo abbiano visibilità), probabilmente lo menzionerò faccia a faccia faccia (sperando di lasciare almeno qualcuno con un fastidioso senso che "Accidenti, penso che Damon abbia detto qualcosa sull'aggiornamento di quello"), e naturalmente avrei lasciato un commento nel codice al punto in cui l'SDK è stato incluso in modo che nessuno potrebbe aggiornarlo senza avere la possibilità di vederlo. Potrei vedere se potrei farlo anche da qualche parte sulla nostra wiki di sviluppo, anche se ciò è fatto più con un occhio di riguardo ai futuri ingaggi, non alla squadra attuale.

Ci vogliono solo un paio di minuti in più rispetto al tempo necessario per incontrarlo e scoprire il problema. Certamente non deciderò di utilizzare uno dei meno usati e meno segnali della nostra documentazione e lascerò perdere.

Dovrebbe essere nella cronologia dei commit ma non dovrebbe essere solo nella cronologia dei commit, immagina per un momento di assumere un nuovo sviluppatore. Ti aspetti che il nuovo sviluppatore legga ogni messaggio di commit per gli ultimi 10 anni del tuo progetto perché un paio di questi sarà fondamentale per capire la tua base di codice?

Secondo dire la situazione ma non il codice cambia, stai andando a fare commit di "documentazione" in modo che tu possa aggiungere messaggi di commit lungo le linee di "messaggio di commit dalla revisione 5432 non è corretto, ecco la situazione attuale".

Non sono sicuro di come la tua squadra comunichi, ma credo che il modo più efficace per dire questo sia prima inviare ed inviare email al gruppo email del team, contrassegnato come "URGENTE" con il corpo che dice

Guys, we can't use SDK v x.y.z because it causes the Foo buffer to overflow and the Bar service will crash. Stick with version x.y.y

Questo è quello che abbiamo fatto qui ed è il modo più affidabile per ottenere il messaggio là fuori. Se veramente vuoi essere pignolo (e se il tuo sistema di posta elettronica lo consente), richiedi una "conferma di lettura" sull'email.

Una volta che hai detto tutto il team, una documentazione più dettagliata dovrebbe essere inserita in una wiki del team. Questo può variare 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 altro posto per documentare questo tipo di problema potrebbe essere nel codice sorgente stesso, anche se potrebbe non funzionare sempre. Se SDK version ... viene fatto riferimento solo in uno o due posti ovvi, puoi includere una nota su non aggiornare.

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

Qualcosa di simile dovrebbe essere stato inserito nei commenti di commit, ma trarrà vantaggio dall'essere in altri luoghi.

Chiunque decida di aggiornare, deve avere i fatti. Quella persona potrebbe non vivere nel controllo del codice sorgente. Cosa accadrebbe se qualcuno avesse letto su 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 di simile si è fatto strada nel controllo della versione e dovresti raccomandare a tutti di usare queste informazioni il più possibile. Solo la tua squadra può decidere dove qualcuno sta andando a fare una ricerca in qualsiasi documentazione, controllo del codice sorgente o bug tracker per ottenere quante più informazioni possibili sull'argomento. Altrimenti, lo dimenticherai, qualcuno lo farà comunque, e sarai fortunato se fa jogging sulla memoria di qualcuno e lo fa rotolare di nuovo velocemente.

La storia è un ottimo posto dove inserire i dati destinati a un lettore che la sta cercando coscientemente e ha un senso generale di dove dovrebbe essere. È un brutto posto dove inserire dati che devono essere offerti ad un utente, piuttosto che ricercati.

Le cronologie sono corpi molto grandi di testo relativamente non ordinato. Solitamente sono destinati a fornire a uno sviluppatore informazioni dettagliate su cosa è cambiato e perché è stato modificato. Questo può essere un sovraccarico di informazioni a meno che non si sappia cosa stanno cercando.

Se un utente non sa cosa sta cercando, allora le informazioni vengono rapidamente nascoste sotto centinaia di registri di commit e non hanno nessuno strumento per potare la pila di informazioni di fronte a loro.

Interpreto questa situazione con due problemi di base, probabilmente tre.

• Un upgrade SDK indesiderato è stato effettuato nell'origine, dove potrebbe influire negativamente sul prodotto.
• Dalla domanda: il contributore che ha eseguito l'upgrade indesiderato non era a conoscenza di una precedente decisione specifica di non effettuare l'upgrade.

Il primo di questi, a mio parere, è il più serio. Se un aggiornamento SDK indesiderato può essere inserito nel codice, possono verificarsi altri problemi.

Qualcuno ha suggerito di aggiungere un caso di test unitario che fallirà se rileva l'aggiornamento. Mentre impedirebbe l'aggiornamento, credo che questo sia un percorso pericoloso, che porta a flusso di lava tempo. Sembra inevitabile che a un certo punto in futuro l'SDK verrà aggiornato, per introdurre nuove funzionalità o correzioni di errori, o perché la vecchia versione non è più supportata. Immagina gli argomenti di graffiatura della testa, forse anche, che si verificheranno quando un tale test unitario fallirà.

Penso che la soluzione più generale sia quella di adattare il processo di sviluppo. Per git, utilizza la richiesta di pull processo. Per Subversion e gli strumenti precedenti, utilizza le filiali e diff. Ma hai qualche processo che consente agli sviluppatori senior di intercettare questo tipo di problemi prima che fanno parte del codice e influenzano altri sviluppatori.

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

Ma per rispondere direttamente alla domanda originale, sono d'accordo con gli altri che aspettano che tutti gli sviluppatori leggano completamente l'intera cronologia delle revisioni del codice, note di rilascio, ecc. per avvisi come questo è uno spreco di tempo prezioso. Cosa c'è di sbagliato in una breve e-mail di squadra?

Possibile terzo problema: perché l'aggiornamento non è richiesto in primo luogo? Chiaramente almeno uno sviluppatore ha pensato che l'aggiornamento sarebbe stato una buona cosa. Ci sono molti buoni motivi per ritardare un aggiornamento, ma anche molti cattivi. Fai attenzione a evitare il flusso di lava (codice di retrocompatibilità non necessario) e culto del carico ("non possiamo aggiornarlo, ma non so perché ") anti-modelli!

Direi che aggiungere quel tipo di informazioni a una cronologia di commit è ok ma deve ancora essere documentato correttamente. Recentemente abbiamo iniziato a utilizzare la confluenza (di atlassian). È ricercabile, puoi impostare determinate pagine come preferiti, ecc.

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

Espandendo sulla risposta di Karl , vorrei seguire un approccio che applica automaticamente la restrizione come parte del check-in processo stesso. Hai bisogno di qualcosa che non richieda azioni proattive per conto dello sviluppatore, come la lettura di un doc / wiki / README e non può essere ignorato in modo nascosto.

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

Un'alternativa potrebbe essere un check-gating che fallirà con una qualche forma di unit test che valuti direttamente o indirettamente la versione dell'SDK, come menzionato da Karl.

Apprezzo che questa risposta sia molto centrata su TFS, ma probabilmente esistono caratteristiche simili nei sistemi di controllo versione / CI che si applicano alla tua situazione (se non TFS).