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


Você é um desenvolvedor e usa o Git para um de seus projetos? Você deseja compartilhar com seus usuários as alterações que você fez, mas não sabe como esse artigo foi feito para você.

Na última parte desta série, eu estava compartilhando com você como escrever uma boa mensagem de confirmação.

Dei a você uma visão geral dos benefícios de escrever um bom commit e compartilhei com você a possibilidade de gerar um changelog.

Neste artigo, você descobrirá o que é um registro de alterações e duas maneiras de gerá-lo, um simples e um sofisticado.

O que é um changelog?

Um changelog é um compartilhamento de arquivos, uma lista cronologicamente ordenada das alterações que você fez no seu projeto. Muitas vezes, é organizada com essa estrutura: a versão com a data seguida por uma lista de recursos adicionados, aprimorados e removidos.

Globalmente, existem duas maneiras de escrever um log de alterações:

  • da maneira usual: crie um arquivo de texto e comece a enumerar todas as suas alterações com uma data específica
  • a escolha do desenvolvedor (também conhecida como opção lenta): gere automaticamente seu log de alterações a partir das mensagens de confirmação. Eu tenho boas notícias para você; é isso que você aprenderá neste artigo!

“Um changelog é um log ou registro de todas as alterações notáveis ​​feitas em um projeto. O projeto geralmente é um site ou projeto de software, e o changelog geralmente inclui registros de alterações, como correções de bugs, novos recursos etc. ” – Wikipedia

Por que é essencial

Acho que, mesmo agora, você está se perguntando por que é essencial e por que deveria dedicar algum tempo para criá-lo.

Um changelog é um tipo de resumo de todas as suas alterações. Pode ser facilmente compreensível por seus usuários usando seu projeto ou pelos desenvolvedores que trabalham nele.

Em um mundo em que tudo está evoluindo rapidamente, o usuário precisa conhecer o site / software que está usando. Você provavelmente ficará surpreso, mas as pessoas gostam de ler postagens de blog ou uma página de atualização em seu site.

Para um desenvolvedor, por exemplo, se o projeto for grande, pode ser interessante saber como evolui o software em que ele está trabalhando.

Outro exemplo, se você estiver trabalhando em código aberto, poderá encontrar um arquivo “CHANGELOG.md” no repositório do GitHub. Este arquivo tem como objetivo informar os colaboradores das atualizações mais recentes do projeto.

Registro de alterações de Angular.js
CHANGELOG.md de Repositório Angular.js no GitHub

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.

Registro de alterações do TickTick Android
TickTick “Novidades” no Android

Registro de alterações do TickTick IOS
TickTick “Novidades” no 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

// Output
commit 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 #17006

commit ff963de73ab8913bce27a1e75ac01f53e8ece1d9
Author: Chives 
Date:   Thu Feb 6 19:05:57 2020 -0500

    docs($aria): get the docs working for the service
    
    Closes #16945

commit 2b28c540ad7ebf4a9c3a6f108a9cb5b673d3712d
Author: 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

// Output
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__ property

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

$ 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

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.

Exemplo de registro de alterações gerado automaticamente
Registro de alterações gerado automaticamente com a ferramenta gerar-registro de alterações

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.





Fonte

Leave a Reply

Your email address will not be published. Required fields are marked *