Idea principale

Lo stato attuale di un repository dice che cosa fa il prodotto oggi, e nient'altro. Un Product Manager che vi legge che un limite di esportazione è fissato a cinquanta righe ottiene il comportamento, non il motivo: il codice non conserva alcuna traccia del fatto che si sono provate duecento righe, poi abbandonate per una questione di tempi di risposta.

Eppure questa traccia esiste, un livello più sotto. I commit, le pull request e le merge request formano una dimensione temporale dello stesso repository: dicono come si è arrivati allo stato attuale. Una discussione di revisione del codice contiene l'obiezione di uno sviluppatore, il vincolo tecnico che ha costretto a discostarsi dalla richiesta iniziale, il compromesso accettato, la correzione fatta tre giorni dopo il rilascio perché era emerso un caso limite.

La distinzione utile non passa quindi tra il codice e i documenti, ma tra due letture dello stesso repository. Lo stato risponde alle domande di comportamento — quale regola si applica, dov'è il limite. La storia risponde alle domande di motivo — perché questo valore, perché questo rifiuto, perché questo comportamento è cambiato tra marzo e giugno. Sono due fonti distinte che si consultano in modo diverso, e confonderle porta a cercare nello stato ciò che non c'è mai stato.

Perché è importante

Recupera una parte di ciò che si credeva perduto designando il codice come fonte di verità. L'obiezione abituale — «il codice dice che cosa, mai perché» — vale per il suo stato, non per la sua storia; una parte del ragionamento di prodotto è stata scritta, semplicemente non dove la si cerca.

Cambia anche ciò che ci si aspetta da una revisione del codice. I commenti di una merge request smettono di essere una conversazione usa e getta tra due sviluppatori: sono l'unico posto in cui la scelta reale è stata registrata nel momento in cui veniva fatta, senza passare per un documento redatto a posteriori.

Sfumature e limiti

La storia è loquace solo se qualcuno l'ha fatta parlare. Un repository i cui messaggi di commit dicono «fix» e le cui merge request vengono integrate senza un commento non conserva alcun intento: lo strato esiste ed è vuoto.

Anche la collocazione inganna. Le discussioni più ricche vivono nella forge — GitHub, GitLab — e non nel repository clonato; una riscrittura della storia che schiaccia i commit si porta via, di passaggio, ciò che vi era stato annotato.

Infine, un intento ritrovato ha una data. La ragione di una scelta fatta tre anni fa spiega quella scelta; non giustifica la regola attuale, che può essere stata riscritta nel frattempo per tutt'altro motivo, senza che niente colleghi i due momenti.

Domande aperte

• Da che cosa si riconosce che una discussione di merge request merita di essere promossa a decisione di prodotto scritta, invece di restare dove è registrata?