Changelog: o guia do desenvolvedor para documentar e compreender alterações de software

Imagine que você é um viajante intergaláctico em busca da resposta para a pergunta fundamental da vida, do universo e tudo mais. Você está explorando o vasto espaço cósmico e, a cada planeta que visita, encontra tecnologia alienígena que precisa entender e usar para continuar sua jornada.

Se você é um fã, já deve ter sacado que eu estou falando do livro Guia do Mochileiro das Galáxias de Douglas Adams.

Assim como Arthur Dent, o personagem principal de "O Guia do Mochileiro das Galáxias", se vê em situações inesperadas no espaço, as pessoas desenvolvedoras de software muitas vezes se deparam com desafios imprevistos. O problema é que, sem um guia claro para as mudanças no código alheio, é como se você estivesse perdido no espaço sideral. Fica inviável a navegação por um código, por exemplo, gerido por mais de um time. Ou pior, imagina se esse mesmo código tem sido mantido por gerações de desenvolvedores e times diferentes ao longo de meses ou até mesmo anos?

Mas... o que isso tem a ver com Changelogs?

É o que vamos descobrir!!

Neste artigo você irá aprender:

• O que são Changelogs;
• Para que servem;
• Qual a importância de criar Changelogs para seu software;
• Exemplos de Changelogs;
• E muito mais!

Então pegue a sua mochila, sua toalha e vamos lá!!!

Changelogs: O Guia do Desenvolvedor

Se você está confuso com as referências aqui utilizadas, vamos adotar um outro contexto, mas ainda estaremos falando de livros, Ok?

Imagine que você é o editor de um livro fascinante de suspense e investigação policial, em que cada capítulo é igual ao anterior só que com detalhes importantíssimos que irão ajudar o leitor a desvendar um mistério de pouquinho em pouquinho. Cada capítulo desse livro representa uma nova versão, e você como editor precisa saber exatamente o que mudou a cada revisão, para que tenha certeza de que não está adicionando detalhes repetidos, pistas que não dizem nada, etc.

No entanto, como fazer isso sem ter anotado tudo de forma detalhada? Você precisa saber em qual capítulo deu determinada pista, ou dica. Você então anota isso como uma espécie de ‘índice de mudanças’ onde você pode consultá-lo e saber exatamente o que mudou.

É aqui que entra o "Changelog", do inglês change mudança e log registro. Um changelog é como um índice de mudanças para seu software, registrando todas as alterações feitas em uma versão específica. Imagine que cada vez que um novo capítulo é adicionado ou uma correção é feita em seu livro, alguém o anota com a data e uma breve descrição. Isso é exatamente o que um changelog faz para o seu software. Um changelog que registra todas as descobertas e mudanças no seu software.

Agora, vamos entender mais alguns motivos do porque changelogs são importantes no desenvolvimento de software.

Vamos lá!

Por que Changelogs são Vitais?

Assim como o Guia do Mochileiro das Galáxias é vital para viajantes intergalácticos, os changelogs são essenciais para os desenvolvedores de software e para os usuários finais, quem vai utilizar o software. Abaixo veremos alguns desses motivos:

1. Depuração de Software: Quando você se depara com um problema, o changelog funciona como um "Guia" que o ajuda a entender o que mudou e por quê. Com isso você saberá exatamente o que mudou, o que está diferente entre as versões e conseguirá de forma mais fácil identificar o que pode ter causado o problema.
2. Colaboração Eficiente: Em equipes de desenvolvimento, onde você terá que explicar para outras pessoas que não necessariamente serão devs o que é o seu código, o que ele faz e o que mudou de uma versão pra outra. Os changelogs mantêm todos na mesma página.
3. Comunicação com Usuários Finais: Assim como Arthur queria saber o que estava acontecendo no universo, os usuários finais querem saber o que há de novo em suas ferramentas e aplicações. Dessa forma, você cria um documento que poderá ser lido por pessoas (devs e não devs) que irão utilizar seu software, biblioteca, pacote, etc., e elas saberão o que mudou entre as versões. Isso fará com que elas se mantenham atualizadas e não saiam por aí usando seu software de qualquer forma.

Quem se Beneficia de um bom Changelog?

Tanto os desenvolvedores quanto os usuários finais se beneficiam de um changelog bem mantido. Os desenvolvedores têm um "Guia" para entender e organizar as mudanças, enquanto os usuários finais obtêm informações sobre melhorias e correções. Então todo mundo sai ganhando, certo?

Mas como escrever um bom Changelog? O que ele precisa ter para ser claro, informativo e conter as principais mudanças entre as versões?

É isso que iremos conhecer agora!

Princípios para um Changelog Eficaz

Embora esses princípios possam ter pequenas variações de pessoa para pessoa, eles são amplamente aceitos e desempenham um papel crucial na criação de changelogs que sejam claros e valiosos para todos os envolvidos, desde desenvolvedores até usuários finais.

• Legibilidade: Os changelogs devem ser escritos de forma clara e compreensível, pois lembre-se que serão destinados a pessoas diversas. Elas que lerão os changelogs, então certifique-se de que eles são de fácil leitura.
• Organização Cronológica Inversa: Assim como a viagem de Arthur começa no fim do mundo, as alterações mais recentes devem estar no topo. Apresente as versões mais recentes no topo do changelog, seguindo uma ordem cronológica inversa (da mais recente para a mais antiga). Isso garante que os usuários visualizem primeiro as atualizações mais recentes.
• Formato de Data Padrão: Use datas no formato AAAA-MM-DD (por exemplo, 2022-01-13). Isso ajuda na clareza e na referência temporal. Mas isso não é uma regra, e você pode usar outros formatos de datas como DD-MM-AAAA, ou por extenso como: “18 de Setembro de 2023”, ou um período (07 de Julho - 08 de Agosto, 2023). Faça o que faz mais sentido dentro do seu contexto.
• Categorização de Mudanças: Use categorias como "Adicionado", "Alterado", "Obsoleto", "Corrigido", "Removido" e "Segurança" para organizar as alterações. Aqui podemos nos aprofundar um pouco mais em cada uma dessas categorias:
  • Adicionado: Esta categoria abrange todos os novos recursos que foram incorporados desde o último lançamento.
  • Alterado: Use essa seção para destacar quaisquer mudanças notáveis na funcionalidade existente do software.
  • Obsoleto: Aqui, identificamos recursos que já foram considerados estáveis em versões anteriores, mas agora estão obsoletos e foram removidos.
  • Corrigido: Esta categoria lista todos os bugs ou erros que foram identificados e corrigidos durante o processo de desenvolvimento.
  • Removido: Qualquer recurso que tenha sido excluído e já não está presente no software é mencionado aqui.
  • Segurança: Esta seção serve como um alerta para os usuários, incentivando-os a atualizar o software para evitar possíveis vulnerabilidades de segurança.
• Destaque o Uso do Versionamento Semântico: É relevante mencionar se o Versionamento Semântico foi aplicado ou não nas versões, proporcionando transparência quanto ao sistema de numeração de versões adotado.

Para fixar melhor esses princípios, iremos ver alguns exemplos de entradas de log de alterações, ou seja, as mensagens do changelog que mostram o que há de novo e mais relevante nas novas versões.

Vamos lá!

Exemplos

Vamos explorar algumas entradas de log de alterações inspiradas nas aventuras de Arthur Dent:

Exemplo 1:

29/08/2023 Ford Prefect <[email protected]>

Módulo de Tradução Babelfish Atualizado: Agora traduz 42 idiomas, incluindo "Vogonês.

- babelfish.js (babel_translate): Melhorias na tradução de idiomas alienígenas.
- babelfish.config (config_languages): Adicionados idiomas alienígenas à lista de suporte.

Note que temos a data, um título, nesse caso o nome e email de quem fez a alteração. Temos uma descrição com o que foi feito nessa nova versão e temos os arquivos que foram modificados, com uma descrição do que foi alterado neles também.

Exemplo 2:

15/06/2023 Zaphod Beeblebrox <[email protected]>

Unidade de Propulsão Infinita Implementada: Prepare-se para a velocidade da luz!

- hyperdrive.c (activate_hyperdrive): Agora é possível viajar no tempo e no espaço.
- ship.config (config_hyperdrive): Configurações para a nova unidade de propulsão adicionadas.

Da mesma forma que o anterior. Os dois exemplos estão em ordem cronológica inversa, do mais recente para o mais antigo.

Nestes exemplos podemos notar algumas semelhanças. E isso não é por acaso, inclusive são dicas de como escrever melhor seus changelogs.

Confira:

• Linhas de Cabeçalho: Comece com uma linha de cabeçalho que resuma a mudança, como um título de capítulo no Guia.
• Descrições Claras: Forneça descrições claras das mudanças, explicando por que elas são necessárias, assim como o Guia explica os lugares a serem visitados.
• Comentários de Código: Assim como Arthur não explicaria o funcionamento de um dispositivo alienígena no Guia, os detalhes técnicos devem estar nos comentários de código, não no changelog.
• Listagem de Entidades Alteradas: Liste explicitamente os arquivos e funções alterados sempre que possível. Isso é como marcar os pontos de referência no Guia.

Aprofundando nos Changelogs

Para quem está tendo o contato pela primeira vez com este tema, podem ser muitas informações e você deve estar com a cabeça cheia de dúvidas. Mas não se preocupe que vamos tentar sanar algumas delas.

Qual o formato de um Changelog?

Não há um formato padrão,mas você pode se basear no GNU Changelog Style Guide que em alguns casos servirá muito bem como referência para você escrever seu changelog da melhor forma possível.

Como nomear um arquivo de Changelog?

Assim como a distância do sol e a terra para Betelgeuse é relativa da mesma forma o nome de um arquivo de changelog é relativo. Novamente não tem um padrão aqui, o consenso é que deve ser fácil para as pessoas desenvolvedoras e usuários finais encontrarem quaisquer mudanças. Mas como exemplo você pode ver arquivos com os nomes de HISTORY.txt, RELEASES.txt, NEWS.md, NEWS.txt, etc.

Caso tenha interesse em se aprofundar um pouco mais você pode conferir outras informações e dúvidas frequentes na página CHANGELOG.md.

Onde encontrar exemplos de Changelogs?

Muitas empresas possuem seu próprio registro de alterações, os changelogs, e você pode conferir alguns exemplos abaixo:

• Stripe
• Github
• Slack
• Notion

Changelogs como um "Guia"

Pense nos changelogs como o "Guia do Mochileiro das Galáxias" que explica como as versões anteriores eram diferentes da versão atual. Eles são como os registros das aventuras de Arthur Dent, detalhando suas experiências em planetas distantes.

Nestes exemplos você pode ter notado muitas semelhanças e/ou diferenças entre eles, mas verá que os princípios dos bons changelogs se mantém comum a todos.

Se quiser olhar mais exemplos de Changelogs de empresas líderes, recomendo dar uma olhadinha neste link aqui!

Vale ressaltar que os changelogs aparecem não somente em softwares da web, como bibliotecas, design systems, programas como os que vimos anteriormente. É comum você encontrar changelogs em outros cenários, como em atualizações de aplicativos e jogos, e até versões recentes de sistemas operacionais e de dispositivos móveis.

Conclusão

Essa viagem nos deu muito conhecimento para anotar em nossos Guias de Desenvolvedor de Software. Aqui aprendemos o que são Changelogs, a importância deles para nosso software, quais os princípios para escrever bons changelogs, exemplos e muito mais. Eu estou realmente muito feliz com o que aprendemos hoje.

Mas assim como o Mochileiro das Galáxias eu recomendo que você continue explorando esse vasto universo de possibilidades. Se quiser se aprofundar mais sobre controle de versões, versionamento semântico, recomendo que você faça uma parada no artigo Versionamento Semântico (SemVer): uma breve introdução.

Se você quer algo mais desafiador, uma aventura na galáxia Front-end, especificamente no planeta React, recomendo fazer a formação Next.js e Tailwind: construindo um design system. Nela você encontrará novos conhecimentos e desafios, como criar um design system do zero, aplicar a metodologia do Atomic Design em seus projetos React, irá aprender a publicar uma biblioteca de componentes e a lidar com versionamento, breaking changes, licença, documentação e muito mais.

Eu vou ficando por aqui, espero que você tenha se divertido lendo este artigo. Se gostou, compartilha com a comunidade, marca a gente usando os perfis da Alura nas redes sociais e não esquece de usar a hastag #AprendiNaAlura.

Até a próxima!