Guia para Git para iniciantes – O que é um Changelog e como gerá-lo

Onde os encontramos?

Changelogs estão por toda parte! Ok, geralmente é com um estilo e local diferentes, mas literalmente em todos os projetos.

Eu criei uma pequena lista com alguns lugares onde você pode encontrar um changelog.

• Uma postagem no blog. Um registro de alterações pode ser entregue em um artigo que compartilha os últimos recursos ponto a ponto.
• Um arquivo “CHANGELOG.md” em um repositório do GitHub.
• Uma seção Changelog em seu site / software favorito. Um exemplo com a ferramenta de gerenciamento de tarefas TickTick.
• Em “Novidades” no Android e na loja IOS.

Geração automática de alterações

Nesta parte, vamos gerar nosso primeiro changelog juntos.

Ao executar esta tarefa, você entenderá por que pode ser útil confirmar seguindo algumas regras.

Um commit excelente e explícito não precisa ser modificado e pode ser adicionado diretamente ao changelog.

Se você estiver interessado em gerar um arquivo necessário sem nenhuma personalização ou embelezamento, recomendo a primeira maneira; caso contrário, o segundo é melhor.

Nota: Alguns sites, como Keep A Changelog estão explicando que você não deve fazer um changelog apenas copiando e colando seus commits git (consulte a maneira simples). Na verdade, eu recomendo tentar evitar dessa maneira se você estiver produzindo um produto profissional. No entanto, atualmente, existem alguns geradores avançados que permitem alterar seus logs do git em changelogs (consulte a maneira sofisticada).

Como gerar um log de alterações (a maneira simples)

Ao usar essa primeira maneira, você não precisa de nenhum pré-requisito. Tudo que você precisa é digitar alguns comandos dentro do seu repositório Git.

Como um lembrete simples, quando você digita “git log”, uma lista de todos os seus commits é exibida.

$ git log// Outputcommit f6986f8e52c1f889c8649ec75c5abac003102999 (HEAD -> master, origin/master, origin/HEAD)Author: Sam Katakouzinos 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 #17006commit ff963de73ab8913bce27a1e75ac01f53e8ece1d9Author: Chives Date:   Thu Feb 6 19:05:57 2020 -0500    docs($aria): get the docs working for the service        Closes #16945commit 2b28c540ad7ebf4a9c3a6f108a9cb5b673d3712dAuthor: comet Date:   Mon Jan 27 19:49:55 2020 -0600    docs(*): fix spelling errors        Closes #16942

Este comando pode receber alguns parâmetros. Vamos usá-los para alterar a saída e obter uma versão melhorada para gerar nosso changelog.

Digitando o seguinte comando, você terá uma saída com uma confirmação por linha.

$ git log --oneline --decorate// Outputf6986f8e5 (HEAD -> master, origin/master, origin/HEAD) docs(developers): commit message format typoff963de73 docs($aria): get the docs working for the service2b28c540a docs(*): fix spelling errors68701efb9 chore(*): fix serving of URI-encoded files on code.angularjs.orgc8a6e8450 chore(package): fix scripts for latest Node 10.x on Windows0cd592f49 docs(angular.errorHandlingConfig): fix typo (wether --> whether)a4daf1f76 docs(angular.copy): fix `getter`/`setter` formattingbe6a6d80e chore(*): update copyright year to 202036f17c926 docs: add mention to changelogff5f782b2 docs: add mention to changelog27460db1d docs: release notes for 1.7.9add78e620 fix(angular.merge): do not merge __proto__ property

É melhor, mas vamos ver o que podemos fazer com o seguinte.

$ git log --pretty=”%s”// Outputdocs(developers): commit message format typodocs($aria): get the docs working for the servicedocs(*): fix spelling errorschore(*): fix serving of URI-encoded files on code.angularjs.orgchore(package): fix scripts for latest Node 10.x on Windowsdocs(angular.errorHandlingConfig): fix typo (wether --> whether)docs(angular.copy): fix `getter`/`setter` formattingchore(*): update copyright year to 2020docs: add mention to changelogdocs: add mention to changelogdocs: release notes for 1.7.9fix(angular.merge): do not merge __proto__ property

Com este, você pode imprimir a lista de confirmações com o estilo desejado.

O “% s” corresponde ao próprio título de confirmação. Você pode modificar a sequência para estilizar sua confirmação como desejar.

No nosso caso, queremos criar uma lista.

$ git log --pretty="- %s"// Output- 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__ property

Você fez isso! Você criou um registro de alterações simples.

Nota: Se você quiser ir além, salve o registro de alterações mais rapidamente. Em vez de copiar e colar o resultado em um arquivo, redirecione-o para o seu terminal digitando “git log –pretty =” -% s “> CHANGELOG.md”

Como gerar um changelog (a maneira sofisticada)

Pré-requisitos

Agora, vamos explorar uma maneira sofisticada de gerar um log de alterações. A idéia por trás do processo permanece a mesma, mas desta vez vamos usar outras ferramentas para nos ajudar.

Você lembra quando na última parte desta série Eu escrevi sobre as diretrizes do Git?

Nota: As diretrizes do Git são um conjunto de regras para escrever melhor seu commit. Isso ajuda você a colocar uma estrutura em seu commit.

Ao usar uma diretriz para o seu projeto, você pode usar ferramentas para gerar um registro de alterações. Na maioria das vezes, essas ferramentas são melhores porque permitem criar um registro de alterações formatado de remarcação.

Neste exemplo, usaremos um gerador simples que funciona com a maioria das diretrizes. Seu nome é “generate-changelog“, Está disponível no NPM (o Node Package Manager).

Essa ferramenta criará um registro de alterações estilizado, mas não é o que possui mais recursos. Decidi usá-lo porque é um excelente exemplo para iniciantes. Se você quiser ir além, consulte a lista de ferramentas de registro de alterações abaixo:

Aqui estão algumas ferramentas para fazer isso:

Nota: Antes de instalar a ferramenta, você precisa ter o NPM instalado no seu computador. Se não for o caso, convido você a siga o site oficial (ele ajudará você a instalar o Node e o NPM).

Para instalar o pacote no seu computador, digite o seguinte comando no seu terminal.

$ npm install generate-changelog -g 

Depois de fazer isso, ele é instalado!

Como usá-lo

Para que este pacote funcione, você precisa seguir uma diretriz usando este padrão “type (category): description [flags]”. Neste exemplo, usarei o repositório Angular.js GitHub porque eles o usam.

Agora você pode digitar o comando generate no seu terminal dentro do seu repositório GitHub.

$ changelog generate

Um arquivo “CHANGELOG.md” será automaticamente criado e preenchido com seus registros em um formato de remarcação.

Você pode encontrar um exemplo da saída (com um leitor de descontos, como o GitHub) abaixo.

Conclusão

Espero que você tenha gostado deste guia e entendido como criar um registro de alterações para o seu projeto. Eu acho que é uma boa maneira de demonstrar por que você deve escrever boas mensagens de confirmação.

Sinta-se livre para experimentar outros geradores de changelog e me enviar o resultado!

Se você tiver alguma dúvida ou comentário, entre em contato.

Não perca meu conteúdo, seguindo-me no Twitter e Instagram.

Você pode encontrar outros artigos como este no meu site: herewecode.io.

Quer mais?

• A cada semana, faça uma cotação motivacional com alguns conselhos, um breve tutorial em alguns slides e a foto de um desenvolvedor sobre Instagram.
• Assine a newsletter e obtenha os artigos, cursos, tutoriais, dicas, livros, motivação e outros conteúdos exclusivos mais recentes.