Automação de changelog, e seus limites

Automação de changelog funciona quando automatiza coleta, classificação e publicação, e para em seleção e formulação. Automatize tudo e você entrega um git log formatado; não automatize nada e o changelog é escrito em rajadas, de memória, antes das releases. A pergunta útil é quais partes automatizar, não quanto.

Projetos de automação de changelog falham em uma de duas direções, e ambas são previsíveis desde a primeira reunião de design. Automatize pouco demais e o changelog é um documento que alguém deveria atualizar, o que significa que é atualizado em rajadas, por quem tirou o palito mais curto. Automatize demais e vira um git log formatado: completo, preciso, e lido por ninguém.

Quais partes de um changelog deveriam ser automatizadas?

Três das quatro etapas. Coleta e publicação completamente; classificação como uma primeira passada com override humano; seleção e formulação nunca.

Coleta. Tirar as mudanças de onde elas acontecem (commits, PRs, tickets) e colocá-las em uma lista. Automatize isso completamente. Humanos são ruins nisso, é tedioso, e é a etapa que é pulada sob prazo. Conventional commits ou labels de PR são a matéria-prima usual.

Classificação. Decidir se algo é Added, Fixed, Changed, Deprecated, Removed ou Security. Automatize a primeira passada a partir do tipo de commit ou label da PR, e deixe um humano fazer override. A precisão aqui fica em torno de oitenta por cento só com metadados, e os vinte por cento errados se concentram exatamente nas entradas que importam, porque ambiguidade correlaciona com importância.

Seleção e formulação. Decidir o que um leitor deveria saber e como dizer isso. Não automatize isso. É todo o valor do artefato. Tudo mais é logística.

Publicação. Levar as entradas finalizadas para uma página, um feed, um e-mail, um widget in-app, um canal do Slack. Automatize completamente, e a partir de uma fonte. É aqui que vai a maior parte do esforço manual real, e quase ninguém conta isso. É também a etapa que pode dizer à pessoa que pediu a mudança que ela foi lançada, que é todo o tema de fechar o ciclo de feedback pelo changelog. A metade de e-mail desse passo tem sua própria forma, em o template de e-mail de atualização de produto.

Esse último ponto vale a pena refletir. Equipes tendem a ver o changelog como um problema de escrita, e então passam a maior parte do tempo em distribuição: copiando entradas para uma ferramenta de e-mail, reformatando para in-app, colando no Slack, atualizando uma página de docs. A escrita leva uma hora. A cópia leva uma hora por release, para sempre, e é a parte que uma máquina deveria ter.

O que acontece quando a linha se move?

Mova-a para cima e você recebe um dump de git. Automação total a partir de commits produz bump deps, fix flaky test, wip e address review comments na frente dos clientes. Toda equipe que fez isso depois adicionou um filtro, e o filtro é uma etapa de seleção reintroduzida sob outro nome, com ergonomia pior.

Mova-a para baixo e você recebe rajadas. Coleta totalmente manual significa que entradas são escritas de memória no momento da release. Esse é o modo contra o qual Keep a Changelog avisa logo de início, e se degrada silenciosamente: o changelog parece mantido até a semana em que ninguém teve tempo.

Como se parece um pipeline de automação de changelog?

Quatro etapas, com exatamente um portão humano, colocado onde um rascunho vira público.

1. No merge, derive uma entrada rascunho da PR: tipo a partir de label ou prefixo de commit, título como primeiro rascunho, link de volta para a PR, autora registrada. Coloque-a em um balde não lançado.
2. Qualquer um pode editar qualquer rascunho a qualquer momento, e editar é barato. A maioria recebe uma linha reescrita.
3. Cortar uma release exige que toda entrada no balde esteja editada ou explicitamente marcada como interna. Este portão é todo o design. Sem ele, rascunhos são lançados sem edição na semana corrida.
4. Publicar é um fan-out a partir do conjunto lançado: a página pública, o feed, o e-mail, o widget, o post do Slack. Uma fonte, várias renderizações, sem cópia.

A etapa 3 é o único lugar onde uma pessoa é necessária, e leva cerca de dez minutos por release assim que os rascunhos estão decentes. Onde uma solicitação de cliente está envolvida, o rascunho também carrega a issue que ele fecha, que é o que permite à etapa 4 avisar quem pediu; o template de solicitação de recurso é desenhado para que esse link sobreviva. Onde essa etapa se encaixa no fluxo de release mais amplo é o assunto do processo de gerenciamento de releases.

O que a automação exige dos seus dados?

Nada disso funciona se o changelog é um arquivo Markdown, porque um arquivo não pode ser renderizado em cinco superfícies sem ser reparseado, e parsear prosa é como você acaba com um widget que mostra metade de um título.

Entradas precisam ser estruturadas: um tipo, uma data, uma versão ou identificador de release, um público, um corpo e um link. Aí o arquivo, a página, o feed e o e-mail são todos visões. Esse ponto estrutural é a única coisa que vale a pena acertar antes de escolher uma ferramenta, porque é o que você não consegue adicionar barato depois. Nada disso funciona se uma entrada não for de fato criada para cada mudança que precisa dela; exigir uma entrada de changelog no CI cobre como fazer o pipeline recusar um merge sem entrada, em vez de deixar esse passo por conta da memória.

Nós construímos o changeloop, onde o changelog é primeiro um feed e depois uma página, então leia isso como um interesse em vez de uma recomendação imparcial; o pricing é um repositório grátis sem cartão, suficiente para ver a forma. Ferramentas de changelog é nosso resumo do que mais existe, incluindo os produtos com os quais competimos, e o gerador de changelog faz as etapas de coleta e classificação no navegador se você quiser ver a derivação antes de se comprometer com um pipeline.

O teste

Conte os minutos entre uma mudança ser mergeada e essa mudança ficar visível para uma cliente que não lê o repo de vocês. Se a maioria desses minutos é alguém copiando texto entre ferramentas, a automação de que vocês precisam está na publicação, não na escrita.

FAQ

A IA pode escrever o changelog? Ela pode redigir um. Um modelo ao qual se dá o pull request mergeado produz na maioria das vezes um primeiro rascunho utilizável do título e do corpo, o que é a coleta e a classificação feitas melhor. A seleção, se um leitor deveria saber algo, e a formulação final, ainda precisam da pessoa que conhece o público, e um pipeline que publica rascunhos sem esse portão automatizou a etapa errada.

Qual é a diferença entre um gerador de changelog e automação de changelog? Um gerador transforma commits em uma lista formatada uma vez, sob demanda. Automação roda a cada merge, mantém um balde não lançado, condiciona a release a revisão humana, e publica em cada superfície a partir de uma fonte. O gerador é a primeira etapa do pipeline, executada manualmente.

O changelog deveria ser automatizado a partir de commits ou de pull requests? De pull requests, onde a unidade de mudança é a PR: o título e a descrição são escritos uma vez, para toda a mudança, e a PR liga a issue que fecha. Derivação baseada em commits funciona quando o commit é a unidade e segue uma convenção.

Como se evita que a automação publique mudanças internas? Classifique chore, ci, test, refactor e atualizações de dependências como internas por padrão, e torne a promoção a público um ato deliberado. O padrão inverso, público a menos que alguém esconda, é como bump deps chega aos clientes.

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