Changelog: automatizar ou não automatizar? Eis a questão…

João Roberto da Paixão
4 min readOct 28, 2024

--

Você já leu um Changelog repleto de termos técnicos, sem contexto, sem padrão, que parecia mais um “despejo de logs de commit”? Eu já… E, essa experiência me fez levantar uma questão importante:

Para quem, e por que, estamos escrevendo os Changelogs?

A automatização nos oferece a facilidade de gerar logs detalhados e consistentes, mas será que estamos sacrificando a comunicação clara e empática em nome da eficiência?

Neste artigo, revisito o propósito dos Changelogs e discuto, na minha visão, como uma abordagem mais humana pode ser a chave para transformar esse recurso em uma ferramenta de comunicação eficaz e centrada na experiência de quem o lê.

Qual o propósito de um Changelog?

Definição

Um Changelog é um registro organizado e cronológico de todas as mudanças notáveis feitas em um projeto. Ele serve como uma ponte de comunicação entre os contribuidores e os usuários, detalhando atualizações, melhorias, correções de bugs e outras modificações relevantes.

Objetivos principais

  • Comunicação clara e compreensível: Informar os usuários sobre as mudanças significativas de forma que eles entendam o impacto no uso do software.
  • Registro histórico: Manter um histórico acessível da evolução do software, útil para desenvolvedores, colaboradores e usuários interessados no progresso do projeto.
  • Transparência e confiança: Demonstrar compromisso com a abertura e a transparência, fortalecendo a relação com os usuários.

A automatização dos Changelogs

Vantagens percebidas

  • Economia de tempo: A geração automatizada reduz o esforço manual, permitindo que os desenvolvedores se concentrem em outras tarefas.
  • Consistência: Ferramentas automatizadas garantem um formato uniforme e atualizações regulares.
  • Integração contínua: Facilita a incorporação de changelogs no fluxo de trabalho de desenvolvimento contínuo.

Apesar dessas vantagens, a automatização enfrenta limitações que afetam diretamente a experiência do usuário final.

Ferramentas comuns

Abaixo eu cito algumas ferramentas que geram o Changelog de forma automática a partir das mensagens de commits do Git:

Limitações e desafios da automatização

Falta de contexto e excesso de informações

Ferramentas automatizadas geram logs, mas elas não compreendem o impacto das mudanças no uso do projeto. Um changelog automatizado tende a listar todas as alterações de forma igual, sem distinguir o que realmente importa para o usuário. Isso acaba gerando confusão e sobrecarga de informações.

Comunicação ineficaz

  • Jargões técnicos: Mensagens de commit podem conter termos técnicos que não são acessíveis a todos os usuários.
  • Ausência do “Porquê”: A automatização geralmente não explica as razões por trás das mudanças, deixando os usuários sem entender o propósito das atualizações.

A importância da intervenção humana

Com a intervenção humana, podemos priorizar mudanças realmente importantes para o usuário e omitir detalhes técnicos desnecessários que apenas causariam confusão. O toque humano permite contextualizar cada atualização, destacando não apenas o que mudou, mas por que isso é relevante. Essa abordagem transforma o Changelog em uma ferramenta de comunicação prática e empática, onde as mudanças são sintetizadas de forma a transmitir benefícios claros e impacto real para o usuário.

Gosto muito da “provocação” destacada no projeto Keep a Changelog:

“Não deixe seus amigos despejarem logs de commits no Changelog”.

Por que gastar tempo em um Changelog?

O projeto Common Changelog respondeu a essa pergunta com uma abordagem bem interessante, resumindo em uma palavra: reciprocidade.

Abaixo deixo a tradução completa da resposta:

Gastar uma quantidade modesta de tempo escrevendo um changelog economiza o dobro de tempo para cada leitor.

Em qualquer projeto, independentemente das práticas do git, haverá erros, ruído e falhas de comunicação. Isso é natural. Se necessário, um projeto pode se mover rápido no git e ficar lento para o changelog. O lançamento pode esperar mais 15 minutos.

Na história do git, um novo recurso pode ser descrito de mais de uma maneira porque leva tempo para desenvolver um vocabulário. Os mantenedores mesclarão solicitações de pull imperfeitas para interromper um vai e vem demorado. Os contribuidores esquecem que a qualidade de suas mensagens de commit se deteriora com o tempo, pois o contexto é perdido. E assim por diante.

Escrever o changelog é outro ciclo de feedback para pensar nas coisas. Uma chance de olhar o panorama geral: como as solicitações de pull recentes funcionam juntas? Algo foi esquecido? O número da versão reflete as mudanças com precisão? Talvez as mudanças estejam quebrando de maneiras imprevistas. Ou (mais raro) o oposto disso, o que pode ser um desperdício de sinalização semver-major.

Não pegue o caminho mais fácil com automação total. Isso resulta em changelogs ruins, derrotando seu propósito.

By: https://github.com/vweevers/common-changelog?tab=readme-ov-file#61-why-spend-time-on-a-changelog

Conclusão

Já pensou que changelogs são uma ferramenta de developer experience tanto para quem trabalha no projeto quanto para quem o usa?

Os changelogs desempenham um papel crucial na comunicação entre contribuidores e usuários. Embora a automatização ofereça vantagens em termos de eficiência, na minha visão, não deveríamos sacrificar a clareza e a eficácia da comunicação.

Lembrar que “Changelogs são para humanos, não máquinas” nos guia a priorizar a experiência do usuário.

Referências

Obrigado por ler! Se você gostou do artigo, dê um clap 👏.

--

--

João Roberto da Paixão
João Roberto da Paixão

Written by João Roberto da Paixão

Eterno aprendiz que compartilha aquilo que aprende. Apaixonado por tecnologia, desenvolvimento pessoal e investimentos. Pai de família, um cara tranquilo =) !

No responses yet