Ideia principal

O estado atual de um repositório diz o que o produto faz hoje, e mais nada. Um Product Manager que lê ali que um limite de exportação está fixado em cinquenta linhas obtém o comportamento, não o motivo: o código não guarda nenhum traço do fato de que duzentas foram testadas e depois abandonadas por uma razão de tempo de resposta.

Esse traço existe, no entanto, um degrau abaixo. Os commits, os pull requests e os merge requests formam uma camada temporal do mesmo repositório: eles dizem como se chegou ao estado atual. Uma discussão de revisão de código contém a objeção de um desenvolvedor, a restrição técnica que forçou um desvio em relação ao pedido inicial, o acordo aceito, a correção feita três dias depois da entrega porque um caso limite tinha aparecido.

A distinção útil não é, portanto, entre o código e os documentos, mas entre duas leituras do mesmo repositório. O estado responde às perguntas de comportamento — qual regra se aplica, onde está o limite. O histórico responde às perguntas de motivo — por que esse valor, por que essa recusa, por que esse comportamento mudou entre março e junho. São duas fontes distintas que se consultam de formas diferentes, e confundir as duas faz procurar no estado o que nunca esteve lá.

Por que isso importa

Isso recupera uma parte do que parecia perdido ao designar o código como fonte de verdade. A objeção habitual — "o código diz o quê, nunca o porquê" — vale para o estado dele, não para a história dele; uma parte do raciocínio de produto foi escrita, só que não onde a procuramos.

Isso também muda o que se espera de uma revisão de código. Os comentários de um merge request deixam de ser uma conversa descartável entre dois desenvolvedores: eles são o único lugar onde a decisão real foi registrada no momento em que era tomada, sem passar por um documento redigido depois.

Nuances e limites

O histórico só é falante se alguém o fez falar. Um repositório cujas mensagens de commit dizem "fix" e cujos merge requests são fundidos sem um comentário não carrega nenhuma intenção: a camada existe e está vazia.

A localização também engana. As discussões mais ricas vivem na forja — GitHub, GitLab — e não no repositório clonado; uma reescrita de histórico por esmagamento dos commits leva junto o que tinha sido registrado ali.

Por fim, uma intenção recuperada tem data. A razão de uma escolha feita há três anos explica aquela escolha; ela não justifica a regra atual, que pode ter sido reescrita desde então por um motivo completamente diferente, sem que nada ligue os dois momentos.

Questões em aberto

• Como reconhecer que uma discussão de merge request merece ser promovida a decisão de produto escrita, em vez de deixada onde está registrada?