Release notes de correção de bugs: entradas úteis

Boas release notes de correção de bugs descrevem o que o usuário viu dar errado, não o que o código fez de errado. Cada entrada diz quem foi afetado, desde quando, se a correção é completa e se o leitor precisa fazer alguma coisa, mesmo que seja apenas “nenhuma ação necessária”.

A maioria das equipes copia uma linha da mensagem de commit. A tabela mostra seis reescritas, e as seções depois dela explicam as regras.

Como escrever uma entrada de correção de bug nas release notes?

Comece pelo sintoma nas palavras do usuário, depois quem foi afetado e desde quando, depois o estado da correção e por fim a ação. Uma ou duas frases costumam bastar. A causa no código pertence ao pull request, onde um engenheiro vai procurá-la.

O leitor procura uma coisa só: “era comigo?” Quatro partes cobrem quase toda entrada:

1. O sintoma. O que apareceu na tela, na resposta da API ou na fatura. Cite o texto do erro, se houve um, porque as pessoas o pesquisam.
2. O alcance. Qual plano, plataforma, versão de API ou formato de dados. “Contas com mais de 50.000 linhas” dá para conferir. “Alguns usuários” não.
3. A janela. Desde qual release ou data, para o leitor decidir se o resultado estranho de ontem era o bug.
4. A ação. Executar de novo, ressincronizar, atualizar, remover uma solução alternativa ou nada.

Se os usuários criaram uma solução alternativa, a linha de ação é onde vocês dizem que ela pode ser apagada.

Qual é a diferença entre uma release note e um changelog?

Um changelog é o registro completo e contínuo das mudanças. Release notes são uma mensagem selecionada e reescrita sobre uma release, para quem decide se deve se importar. Nas correções de bugs, o changelog lista todas e as notas abrem com as que um leitor poderia ter notado.

Um erro de digitação em um tooltip pertence só ao changelog. Uma alíquota de imposto errada nas faturas pertence aos dois. A divisão completa está em changelog vs release notes, e a forma de um bom conjunto de notas está em como escrever release notes.

Keep a Changelog é uma convenção prática para o lado do registro. Ela reserva “Fixed” para qualquer correção de bug e um título “Security” separado para vulnerabilidades, que é a mesma divisão que este artigo faz para o leitor.

Uma correção de bug é uma atualização?

Sim. Uma correção de bug muda o produto, então lançá-la é uma atualização. Pelo versionamento semântico, uma correção compatível com versões anteriores é uma release de patch, por exemplo da 4.2.0 para a 4.2.1.

Se o leitor precisa fazer alguma coisa é outra pergunta, e a nota deve respondê-la. Uma correção que muda o que um chamador correto observa está perto de um breaking change, e breaking changes explica onde fica essa linha.

Quando uma correção merece entrada própria e quando é uma correção menor?

Dê entrada própria a uma correção quando um usuário poderia ter notado o bug, perdido tempo ou dados com ele, ou criado uma solução alternativa. Agrupe-a em uma lista curta de “Correções menores” quando ninguém fora da sua equipe poderia tê-lo visto. Julgue pela experiência do leitor, qualquer que seja o tamanho do diff.

Cada linha do grupo ainda deve dizer algo: “Corrigidos alguns problemas de interface” é um espaço reservado.

Como escrever sobre uma regressão?

Nomeie a release que a introduziu, chame-a de regressão e dê a release que a corrige. Quem foi atingido pelo bug já sabe que quebrou, então uma admissão curta e direta serve melhor que uma redação vaga.

Por exemplo: “Resultados de busca para consultas com hífen voltavam vazios na 4.1.0. Isso está corrigido na 4.1.1. Se você mudou suas consultas para evitar hífens, pode voltar ao que era.”

“Confiabilidade da busca melhorada” soa como evasiva para quem perdeu uma tarde com o bug. Se a causa ainda está sendo confirmada, digam isso, como orienta o guia de release notes de emergência: nunca deixe a nota soar mais certa do que a equipe está.

Como anunciar uma correção de segurança?

Declare a gravidade com clareza, nomeie as versões afetadas e a versão que as corrige, diga a urgência da atualização e inclua o identificador CVE, se houver. Publique detalhes só quando os usuários puderem agir sobre a correção, seguindo um processo de divulgação coordenada quando houve um relator.

A sequência importa: o relator avisa em particular, vocês lançam a correção e a nota pública sai quando os usuários podem se proteger. O processo de divulgação coordenada de vulnerabilidades da CISA coordena relato, análise e divulgação pública de vulnerabilidades. As regras da CVE Numbering Authority governam como os registros CVE são atribuídos e publicados, e no GitHub um advisory de segurança do repositório permite redigir o aviso em particular e pedir um identificador.

Uma entrada de segurança costuma levar quatro fatos:

• O que um atacante poderia fazer, em uma frase e sem prova de conceito.
• As versões afetadas e a versão que corrige.
• A urgência: “atualize hoje” ou “atualize na sua próxima release”.
• Se vocês viram exploração, e o crédito ao relator, se ele concordou.

Deixe de fora os passos do exploit.

O que uma nota deve dizer sobre uma correção de perda de dados?

Diga quais dados foram afetados, como saber se os seus foram e se podem ser recuperados. “Nenhuma ação necessária” raramente é verdade aqui, e a primeira pergunta do leitor é “meus dados sumiram?”.

Uma entrada útil dá a condição que perdeu dados (“excluir uma pasta enquanto uma sincronização rodava”), a janela em que isso era possível, uma forma de conferir (“abra a Lixeira e procure itens de 3 a 9 de setembro”) e o caminho de recuperação. Se os dados não podem ser recuperados, digam isso. Contatem também os clientes afetados diretamente, porque a release note não deve ser o único lugar em que alguém descobre que seus dados foram atingidos.

Por que “Correções de bugs e melhorias de desempenho” é uma nota ruim?

Não dá ao leitor nada sobre o que agir e esconde as correções que alguém esperava. Um cliente que relatou um travamento não sabe se foi corrigido, e um cliente com uma solução alternativa não sabe se deve removê-la.

Há duas alternativas honestas. Se uma release não tem nada que um leitor pudesse notar, não publiquem notas para ela e deixem o changelog guardar o registro. Se tem correções, listem-nas nos termos do leitor:

Antes:
  Correções de bugs e melhorias de desempenho.

Depois:
  Corrigido: a exportação CSV falhava em projetos sem tags.
  Corrigido: o modo escuro escondia o cursor no campo de
  comentário.
  Mais rápido: o painel abre mais depressa em workspaces
  com mais de 100 projetos.

De onde vêm as notas de correção de bugs?

Vêm do pull request que corrigiu o bug e do relato que o originou. Se as palavras de quem relatou viajam com a correção, metade do sintoma já está escrita.

Pedido de funcionalidade ou bug explica por que classificar bem um relato decide quem é o dono dele. No Changeloop, um bug relatado pelo widget vira uma issue do GitHub com a etiqueta bug, e a entrada do changelog é redigida a partir do pull request integrado e retida para uma pessoa aprovar antes de publicar. O template de release notes dá a mesma forma de entrada para escrever à mão: sintoma, alcance, janela, ação.

FAQ

O que as release notes de correção de bugs devem incluir? Cada entrada deve nomear o sintoma que o usuário viu, quem foi afetado, desde qual release ou data, se a correção é completa e o que o leitor precisa fazer, incluindo “nada”.

Toda correção de bug deve ser listada nas release notes? Não. Liste as que um usuário poderia ter notado, perdido tempo com elas ou contornado, e agrupe as correções cosméticas ou internas em uma lista curta de “Correções menores”. O changelog guarda todas as correções para quem precisar consultar uma.

Como escrever release notes para um bug que você mesmo introduziu? Diga que foi uma regressão, nomeie a release que a introduziu e a release que a corrige, e diga aos leitores se podem remover alguma solução alternativa. Uma declaração direta lê melhor que uma redação suavizada.

Como conferir as release notes de um produto que você usa? Procure uma página de changelog ou release notes ligada no menu de ajuda, no rodapé ou na documentação do produto, ou na aba de releases do repositório, no caso de projetos open source.

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: Modelo de notas de versão