Quem escreve o changelog, e quem deveria

Pergunte a um time quem escreve o changelog e a resposta honesta costuma ser “quem lembrar”, que é o mesmo modo de falha que impor uma entrada de changelog no CI existe para consertar em nível mecânico. Mas forçar a existência de uma entrada não decide quem está qualificada para escrever uma boa, e times que pulam essa pergunta tendem a recorrer por padrão a quem for mais fácil de obrigar, geralmente a autora do PR, sem verificar se essa é realmente a pessoa que consegue escrevê-la bem.

Por que a autora do PR não é automaticamente a melhor escritora de changelog?

Porque ela conhece a implementação, não necessariamente o impacto, e esses são tipos diferentes de conhecimento. Onde os conventional commits param cobre essa lacuna pelo lado da mensagem de commit: fix(auth): reject expired refresh tokens está correto e não diz nada a uma cliente, e quem escreveu essa correção é muitas vezes a pessoa menos equipada para traduzi-la, porque passou horas pensando nos termos do bug e perdeu a visão externa do que uma usuária de fato experimentou. Essa é a mesma razão pela qual redatoras técnicas existem como profissão: traduzir implementação em impacto é uma habilidade distinta de ter construído a coisa, e isso exige prática independente de quão boa a desenvolvedora seja no próprio código.

Isso significa que produto ou suporte deveriam escrever cada entrada em vez disso?

Não, porque elas têm a lacuna oposta: sabem o que importa para as usuárias mas nem sempre o que de fato foi lançado, o que produz entradas legíveis mas ocasionalmente erradas em escopo, uma afirmação “agora suporta X” para um recurso ainda atrás de uma flag, ou uma correção descrita como completa quando cobre apenas um de três casos. O modo de falha de entradas escritas por desenvolvedoras é ilegível-mas-preciso; o modo de falha de entradas escritas por PMs é legível-mas-não-verificado. Nenhum papel possui as duas metades do que uma boa entrada precisa.

Como de fato é um modelo de responsabilidade que funciona?

Um rascunho de quem estiver mais perto da mudança, revisado por quem estiver mais perto da usuária, com uma pessoa nomeada responsável pela formulação final em vez de todo mundo assumir que outra pessoa vai pegar os problemas. O rascunho precisa existir e ser preciso mais do que precisa ser bom; uma frase crua escrita por uma desenvolvedora que diz corretamente o que mudou é um ponto de partida melhor do que uma polida mas não verificada, porque reescrever por clareza é mais fácil do que reescrever por correção. O passo de revisão é onde uma PM ou líder de suporte lê o rascunho e faz a única pergunta que pega a lacuna de legibilidade: eu entenderia isso se não tivesse visto o código.

Deveria ser sempre a mesma pessoa responsável, ou isso roda?

Nomeada e estável vence rotativa, pelo menos para a aprovação final. Uma dona rotativa significa que cada entrada é revisada por alguém que re-deriva as convenções do time do zero, o que é exatamente como a voz vai à deriva de entrada em entrada e uma leitora começa a notar que o changelog foi escrito por um comitê. Uma pessoa, ou um grupo estável muito pequeno, acumula julgamento ao longo do tempo, quando dizer “melhorado” versus nomear o número específico, quando uma correção precisa de sua própria entrada versus se dobrar em um lote, e esse julgamento vale mais do que distribuir o trabalho igualmente.

Rascunho (desenvolvedora, do PR):
"Fixed pagination cursor not respecting the `sort` param
in some edge cases."

Revisado (dona do changelog, conferido com o PR real):
"Corrigido: exportações ordenadas por data podiam
retornar resultados fora de ordem além da primeira
página. Agora consistente em todas as páginas."

Um time pequeno precisa de tanto processo assim para uma linha de texto?

Não os papéis como pessoas separadas, mas os dois passos ainda importam mesmo sozinha. Um time de uma pessoa é tanto a desenvolvedora quanto a revisora, e a disciplina que sobrevive nessa escala é fazer a revisão como uma passada mental separada, não pular direto de escrever a correção para publicar uma descrição dela no mesmo fôlego. A armadilha em pequena escala é pular a segunda passada completamente, não a falta de uma segunda pessoa, porque ninguém de fora a impõe, e a lacuna de precisão que essa passada existe para pegar não desaparece só porque a mesma pessoa poderia teoricamente notar seu próprio ponto cego.

O que acontece quando ninguém é responsável pela entrada final?

O changelog se degrada de forma desigual em vez de falhar abertamente, o que é pior porque ninguém percebe até uma leitora apontar. Algumas entradas permanecem nítidas porque quem as escreveu se importava; outras ficam vagas, “várias melhorias e correções de bugs”, porque quem as escreveu estava com pressa e ninguém pegou isso antes da publicação. As restrições de formato do Keep a Changelog pegam desvio estrutural, datas faltando, categorias erradas, mas nada em um template pega uma entrada vaga que está tecnicamente bem formatada, o que é exatamente a lacuna que uma dona nomeada existe para fechar.

FAQ

A dona do changelog deveria ser um papel de engenharia ou de produto? Qualquer um pode funcionar se a pessoa tiver tanto fluência técnica para verificar o escopo quanto distância suficiente da implementação para escrever para uma leitora externa; o cargo importa menos do que se ela consegue fazer as duas metades, ou sabe a quem perguntar sobre a metade que não consegue.

Uma escala rotativa estilo plantão é adequada para a responsabilidade do changelog? Para volume, às vezes, se o time for pequeno demais para uma pessoa revisar tudo; para voz e julgamento, não, porque isso é exatamente o que a rotação corrói. Uma rotação que divide a carga de rascunho enquanto mantém uma revisora estável ganha o benefício sem o desvio.

Qual é o sinal mais rápido de que algo está errado com a configuração atual de responsabilidade? Entradas que são precisas mas ilegíveis, ou legíveis mas erradas em escopo, em um padrão que segue quem as escreveu. Se a qualidade correlaciona com a autora em vez de permanecer consistente, a lacuna está na responsabilidade, não na habilidade de escrever.

A automação reduz o quanto a responsabilidade importa? Ela reduz quanta escrita é necessária, não quanto julgamento é necessário. Automação de changelog cobre o que um pipeline pode gerar com segurança, formatação, publicação, cross-posting; formulação, agrupamento e o que conta como digno de menção continuam sendo decisões humanas independentemente de quanto do pipeline está automatizado.

E se a autora do PR e a revisora discordarem sobre a formulação? A palavra final é da revisora, porque a pergunta que ela está respondendo, uma leitora de fora entenderia isso, é exatamente a que o papel existe para proteger. Isso não torna a leitura da desenvolvedora sem valor: se o desacordo é sobre precisão em vez de formulação, a revisora cede, porque o escopo é a metade que cabe à autora acertar. Separar os dois tipos de desacordo, formulação versus precisão, evita que a maioria deles vire um impasse.

As afirmações técnicas deste artigo não foram revisadas de forma independente. Se algo estiver errado, avise a gente e vamos corrigir.

Relacionado na changeloop: Comparativo de ferramentas de changelog, Gerador de changelog