Artigo original: https://www.freecodecamp.org/news/a-beginners-guide-to-git-what-is-a-changelog-and-how-to-generate-it/
Se você é um desenvolvedor e usa o Git em um de seus projetos, pode ser que queira compartilhar com seus usuários as alterações que fez, mas não sabe como fazer isso. Bem, este artigo é para você.
Em outro momento em minha série de artigos, compartilhei como escrever uma boa mensagem de commit (texto em inglês).
Já mostrei os benefícios de se escrever uma boa mensagem de commit, bem como já havia mencionado a possibilidade de gerar um changelog (em português, algo como um registro das alterações).
Neste artigo, você saberá o que é um changelog e verá duas maneiras de gerá-lo – uma simples e outra um pouco mais sofisticada.
O que é um changelog?
Um changelog é um arquivo que compartilha uma lista cronologicamente ordenada das alterações qu você realizou em seu projeto. Ele geralmente é organizado por versão, com a data seguida de uma lista de recursos adicionados, melhorados ou removidos.
Em geral, há duas maneiras de se escrever um changelog:
- a maneira comum: criar um arquivo de texto e começar a enumerar todas as alterações com uma data específica
- a escolha do desenvolvedor (também conhecida como o modo fácil): gerar automaticamente o changelog a partir de suas mensagens de commit. A boa notícia é que será exatamente essa a maneira que você aprenderá neste artigo!
"Um changelog é um relato ou registro de todas as alterações importantes feitas em um projeto. O projeto geralmente é um site da web ou um projeto de software. O changelog frequentemente inclui registros de alterações como consertos de bugs, novos recursos e assim por diante." – Wikipédia
Por que ele é essencial?
Imagino que, nesse momento, você esteja se perguntando o porquê de ele ser essencial e por que dedicar um tempo para sua criação.
Um changelog é uma espécie de resumo de todas as suas alterações. Ele deve ser fácil de entender para os usuários de seu projeto e para os desenvolvedores que trabalharem nele.
Em um mundo onde tudo se desenvolve rapidamente, o usuário precisa saber se o site da web/software que ele está usando passou por alterações. Você pode se surpreender por isso, mas há quem adore ler publicações em blogs ou páginas de atualizações dos sites da web.
Para um desenvolvedor, por exemplo, se o projeto for grande, pode ser interessante saber como o software no qual ele está trabalhando vem evoluindo.
Se, em contrapartida, você estiver trabalhando em um projeto de código aberto (do inglês, open-source), você poderá encontrar um arquivo "CHANGELOG.md" no repositório do GitHub. O objetivo desse arquivo é informar os colaboradores sobre as atualizações mais recentes do projeto.
Onde eu posso encontrá-lo?
Você verá changelogs em todo o lugar! Claro, eles, frequentemente, têm estilos diferentes e se encontram em locais diferentes, mas eles estão (ou deveriam estar), literalmente, em todos os projetos.
Criei aqui uma lista com alguns lugares onde você pode encontrar um changelog.
- Uma publicação em blog: um changelog pode ser entregue como um artigo compartilhando os últimos recursos, ponto a ponto.
- Um arquivo "CHANGELOG.md" no repositório do GitHub.
- Uma seção de Changelog no seu site da web/software favorito. Aqui temos um exemplo com uma ferramenta de gerenciamento de tarefas, o TickTick.
- Na seção "What's new" (em português, novidades) nas lojas do Android e do IOS.
Geração automática do changelog
Nesta parte, vamos gerar juntos nosso primeiro changelog.
Ao fazer isso, você entenderá a razão pela qual pode ser útil fazer os commits e suas mensagens seguindo algumas regras.
Um commit excelente e explícito não precisa ser modificado e pode ser adicionado diretamente ao changelog.
Se estiver interessado em gerar um arquivo necessário sem o personalizar ou estilizar, recomendo a primeira maneira. Do contrário, a segunda é melhor.
Observação: alguns sites da web, como o Keep A Changelog, explicam que você não deve fazer um changelog simplesmente copiando e colando as mensagens de commit do Git (veja a maneira simples). De fato, eu recomendo tentar evitar essa maneira se estiver trabalhando em um produto profissional.
No entanto, hoje em dia, existem alguns geradores avançados que permitem que você transforme seus logs do Git em changelogs (veja a maneira sofisticada).
Como gerar um changelog (a maneira simples)
Se você usar a primeira maneira, não há pré-requisitos a cumprir. Tudo o que você precisa fazer é digitar alguns comandos no repositório do Git.
Apenas para lembrar, ao digitar "git log", uma lista de todos os seus commits é exibida.
$ git log
// Resultado
commit f6986f8e52c1f889c8649ec75c5abac003102999 (HEAD -> master, origin/master, origin/HEAD)
Author: Sam Katakouzinos <sam.katakouzinos@gmail.com>
Date: Tue Mar 10 11:41:18 2020 +1100
docs(developers): commit message format typo
Any line of the commit message cannot be longer *than* 100 characters!
Closes #17006
commit ff963de73ab8913bce27a1e75ac01f53e8ece1d9
Author: Chives <chivesrs@gmail.com>
Date: Thu Feb 6 19:05:57 2020 -0500
docs($aria): get the docs working for the service
Closes #16945
commit 2b28c540ad7ebf4a9c3a6f108a9cb5b673d3712d
Author: comet <hjung524@gmail.com>
Date: Mon Jan 27 19:49:55 2020 -0600
docs(*): fix spelling errors
Closes #16942Esse comando pode receber alguns parâmetros. Usaremos esses parâmetros para alterar o resultado e para obter uma versão melhorada para gerar nosso changelog.
Ao digitar o comando a seguir, você terá como resultado um commit por linha.
$ git log --oneline --decorate
// Resultado
f6986f8e5 (HEAD -> master, origin/master, origin/HEAD) docs(developers): commit message format typo
ff963de73 docs($aria): get the docs working for the service
2b28c540a docs(*): fix spelling errors
68701efb9 chore(*): fix serving of URI-encoded files on code.angularjs.org
c8a6e8450 chore(package): fix scripts for latest Node 10.x on Windows
0cd592f49 docs(angular.errorHandlingConfig): fix typo (wether --> whether)
a4daf1f76 docs(angular.copy): fix `getter`/`setter` formatting
be6a6d80e chore(*): update copyright year to 2020
36f17c926 docs: add mention to changelog
ff5f782b2 docs: add mention to changelog
27460db1d docs: release notes for 1.7.9
add78e620 fix(angular.merge): do not merge __proto__ propertyJá ficou melhor, mas vamos ver o que podemos fazer além disso.
$ git log --pretty="%s"
// Resultado
docs(developers): commit message format typo
docs($aria): get the docs working for the service
docs(*): fix spelling errors
chore(*): fix serving of URI-encoded files on code.angularjs.org
chore(package): fix scripts for latest Node 10.x on Windows
docs(angular.errorHandlingConfig): fix typo (wether --> whether)
docs(angular.copy): fix `getter`/`setter` formatting
chore(*): update copyright year to 2020
docs: add mention to changelog
docs: add mention to changelog
docs: release notes for 1.7.9
fix(angular.merge): do not merge __proto__ propertyCom ele, você pode imprimir a lista dos commits no estilo que você quiser.
O "%s" corresponde ao próprio título do commit. Você pode modificar a string para estilizar seu commit como quiser.
Em nosso caso, queremos criar uma lista.
$ git log --pretty="- %s"
// Resultado
- docs(developers): commit message format typo
- docs($aria): get the docs working for the service
- docs(*): fix spelling errors
- chore(*): fix serving of URI-encoded files on code.angularjs.org
- chore(package): fix scripts for latest Node 10.x on Windows
- docs(angular.errorHandlingConfig): fix typo (wether --> whether)
- docs(angular.copy): fix `getter`/`setter` formatting
- chore(*): update copyright year to 2020
- docs: add mention to changelog
- docs: add mention to changelog
- docs: release notes for 1.7.9
- fix(angular.merge): do not merge __proto__ propertyVocê conseguiu! Acaba de criar um changelog simples.
Observação: se ainda quiser ir mais longe e salvar seu changelog mais rapidamente, em vez de copiar e colar o resultado em um arquivo, redirecione o resultado para um arquivo em seu terminal, digitando git log --pretty="- %s" > CHANGELOG.md
Como gerar um changelog (a maneira sofisticada)
Pré-requisitos
Agora, trataremos de uma maneira sofisticada de gerar um changelog. A ideia por trás do processo segue a mesma, mas, desta vez, usaremos outras ferramentas para nos ajudar.
Na parte anterior desta série que mencionei previamente, eu escrevi sobre diretrizes do Git.
Observação: as diretrizes do Git são um conjunto de regras para escrever mensagens de commit melhores. Essas diretrizes ajudarão você a adicionar um pouco de estrutura aos commits.
Ao usar uma diretriz para o seu projeto, você pode usar ferramentas para gerar um changelog. Na maioria das vezes, essas ferramentas são melhores, pois permitem que você crie um changelog formatado em markdown.
Neste exemplo, usaremos um gerador simples, que funciona com a maioria das diretrizes. Seu nome é "generate-changelog" e ele está disponível no NPM (o gerenciador de pacotes do Node).
Essa ferramenta criará um changelog estilizado, mas não é a ferramenta com o maior número de recursos. Decidi usá-la, pois é um exemplo excelente para um iniciante. Se quiser se aprofundar, consulte a lista de ferramentas de changelog abaixo:
Aqui temos algumas ferramentas que você pode usar:
Observação: antes de instalar a ferramenta, você precisa ter o NPM instalado em seu computador. Se ainda não o tem, convido você a visitar o site oficial da web (ele ajudará na instalação do Node e do NPM).
Para instalar o pacote em seu computador, digite o comando a seguir no seu terminal:
$ npm install generate-changelog -g Ao fazer isso, ele será instalado!
Como usar
Para fazer com que o pacote funcione, você precisa seguir as diretrizes de uso neste padrão – "tipo(categoria): descrição [flags]". Neste exemplo, usarei o repositório do Angular.js no GitHub.
Agora, você pode digitar o comando generate no seu terminal dentro do repositório do GitHub.
$ changelog generateUm arquivo "CHANGELOG.md" será criado automaticamente e preenchido com seus logs em formato markdown.
Veja aqui um exemplo de resultado (com um leitor de markdown, como o GitHub).
Conclusão
Espero que você tenha gostado deste guia e que, agora, entenda como criar um changelog para o seu projeto. Acho uma boa maneira de demonstrar por que devemos escrever boas mensagens de commit.
Fique à vontade para experimentar outros geradores de changelog!
Se quiser mais conteúdo deste tipo, siga o autor no Twitter, onde ele escreve sobre desenvolvimento para a web, melhoramento pessoal e sobre sua jornada como desenvolvedor full-stack!