Um changelog é um registro detalhado de todas as alterações feitas em seu projeto durante um período de tempo. Um changelog não serve apenas como um ponto de partida para corrigir bugs e erros, mas também é um valioso recurso educacional ao apresentar novos desenvolvedores ao seu projeto.
Neste tutorial, vamos explorar um método para gerar e liberar automaticamente um changelog que usa git hooks e Node.js. Criaremos uma mensagem de commit convencional usando um formato de commit específico chamado Convencional Commits e uma ferramenta chamada Commitizen . Em seguida, usaremos uma biblioteca chamada versão padrão para gerar automaticamente um changelog e uma nova versão de lançamento que segue controle de versão semântico .
Finalmente, vamos tornar nosso changelog compartilhável com a equipe de desenvolvimento para que todos sigam as mesmas convenções no projeto. Você pode encontrar o código final neste repositório GitHub se desejar acompanhar.
Vamos começar!
Estruturação de mensagens de confirmação em confirmações convencionais
A especificação de confirmações convencionais melhora as mensagens de confirmação, fornecendo regras para a criação de um histórico de confirmação específico. Os commits convencionais tornam a geração de um changelog fácil, criando uma versão que usa versionamento semântico.
De acordo com a convenção, a mensagem de commit deve ser estruturada da seguinte maneira:
Vamos examinar os detalhes da estrutura:
O escopo é um substantivo opcional que descreve a parte da base de código que é alterada ou atualizada pelo commit. Por exemplo, em feat (pages), pages é o escopo.
Em versionamento semântico,! correlaciona-se com MAJOR. Quando usado após o escopo,! indica que há mudanças significativas no commit.
corpo é um campo opcional que você pode usar para descrever o commit em mais detalhes. o corpo deve começar uma linha após a descrição. rodapé também é um campo opcional. Por exemplo, um rodapé é BREAKING CHANGE, que se correlacionaria com MAJOR no controle de versão semântica.
Exemplos de mensagem de commit
Vejamos alguns exemplos de mensagens de commit diferentes:
Confirme a mensagem apenas com o tipo e a descrição:
feat: adicione a opção de cobrança para carros
Confirme a mensagem com o tipo, escopo e descrição:
correção (página inicial): altere a largura do título do título
Mensagem de confirmação com BREAKING CHANGE:
refactor (api): remova a API get das reservas BREAKING CHANGE: refactor para usar a API de viagem em vez da api de reservas
Criando nosso projeto
Vamos comece nosso projeto adicionando as ferramentas necessárias para automatizar nosso changelog e lançamento. Primeiro, crie um prompt de comando, onde adicionaremos os seguintes blocos de código.
Vamos criar um projeto baseado em npm e torná-lo um repositório git. Se você deseja automatizar um repositório existente, pode pular esta etapa:
# criar diretório do projeto mkdir changelog # cd no projeto cd changelog # inicializar projeto npm npm init-y # initialize git git init
O bloco de código acima criará um repositório git e um pacote npm com v1.0.0.
Adicione a versão padrão ao nosso projeto
Agora, vamos começar a criar versões para o nosso projeto! Você precisará instalar o pacote npm da versão padrão em seu projeto da seguinte maneira:
npm install–save-dev standard-version
Você também precisará adicioná-lo aos scripts npm:
…”scripts”: {“release”:”standard-version”}…Criando uma versão
Crie um arquivo fictício chamado new-feature e confirme-o da seguinte maneira:
touch new-feature git add new-feature git commit
Adicione a seguinte mensagem git commit:
feat (new-feature): adicione um novo recurso ao nosso projeto
Finalmente, vamos criar uma versão em nosso projeto executando nosso script recém-adicionado:
npm run release
Executar o comando acima mostrará a seguinte mensagem na tela:
> [email protected] release/home/imsingh/Develop/inder/changelog> versão-padrão ✔ versão otimizada em package.json de 1.0.0 a 1.1.0 ✔ versão ampliada em package-lock.json de 1.0.0 a 1.1.0 ✔ criado CHANGELOG.md ✔ alterações de saída para CHANGELOG.md ✔ confirmando package-lock.json e package.json e CHANGELOG.md ✔ tag ging release v1.1.0 ℹ Execute `git push–follow-tags origin master && npm publish` para publicar
A mensagem acima faz o seguinte:
Aumenta o número da versão SemVer de 1.0.0 para 1.1.0 Adicionamos um recurso, portanto, MINOR foi atualizado de 0 para 1 Cria um arquivo CHANGELOG.md, adicionando o conteúdo necessário a ele Confirma as alterações acima, criando uma tag v1.1.0 Imprime uma mensagem para enviar tags e publicar nosso pacote para npm, se necessário
CHANGELOG.md
Agora, se você abrir CHANGELOG.md, verá o seguinte bloco de código, que inclui as alterações feitas acima:
# Changelog Todos notáveis as mudanças neste projeto serão documentadas neste arquivo. Veja \ [versão padrão \] (https://github.com/conventional-changelog/standard-version) para diretrizes de commit. ## 1.1.0 (2021-07-12) ### Features * ** new-feature: ** adicione um novo recurso ao nosso projeto 11c0322
Você também verá a mensagem de confirmação de lançamento padrão criada, que usou o comando git log-1 para fazer um lançamento:
commit #COMMIT_HASH (HEAD-> master, tag: v1.1.0) Autor: #AUTHOR_NAME <#AUTHOR_EMAIL> Data: #COMMIT_DATE tarefa (lançamento): 1.1.0
O tipo de mensagem de confirmação é chore, o escopo é release e a descrição é 1.1.0.
Agora, você tem tudo que precisa para automatizar seu changelog e release! No entanto, escrever manualmente o commit é tedioso e sujeito a erros. Vamos trazer algumas ferramentas para facilitar o processo!
Adicionando Commitizen
Em vez de escrever commits convencionais, você pode usar o Commitizen para gerá-los automaticamente. Commitizen faz perguntas no prompt de comando e gera os commits com base em suas respostas.
Instale o pacote Commitizen da seguinte maneira:
npm install–save-dev commitizen
Agora, inicialize o Commitizen para usar o adaptador changelog convencional:
npx commitizen init cz-convencional-changelog–save-dev–save-exact
Um adaptador é uma configuração que diz ao Commitizen para exibir diferentes tipos de commits em um prompt. Atualmente, há uma variedade de adaptadores disponíveis, mas você pode criar seu próprio adaptador, se desejar.
Agora, para usar o Commitizen, adicionaremos um script npm:
…”scripts”: {“commit”:”cz”}…
Neste ponto, você deve crie um arquivo.gitignore e ignore o diretório node_modules.
Adicione package.json e package-lock.json à área de teste git usando git add. Faremos um commit executando o bloco de código abaixo:
npm run commit
O bloco de código acima também solicitará que você responda às diretivas que se seguem.
type mostra a lista de tipos a partir dos quais você pode selecionar. A lista abaixo veio do adaptador que instalamos anteriormente:
? Selecione o tipo de mudança que você está realizando: talento: Uma nova correção de recurso: Uma correção de bug docs: Mudanças apenas na documentação ❯ estilo: Mudanças que não afetam o significado do código (espaço em branco, formatação, ponto-e-vírgula ausente ons, etc) refactor: Uma alteração de código que não corrige um bug nem adiciona um desempenho de recurso: Uma alteração de código que melhora o desempenho (Mova para cima e para baixo para revelar mais opções)
escopo, no bloco de código abaixo, refere-se ao escopo do commit convencional:
? Qual é o escopo desta mudança (por exemplo, componente ou nome do arquivo): (pressione Enter para pular)
Para uma breve descrição, escreva uma breve explicação do commit convencional:
? Escreva uma descrição curta e imperativa da mudança (máximo de 82 caracteres):
Em uma descrição mais longa, descreva o corpo do commit convencional:
? Forneça uma descrição mais longa da mudança: (pressione Enter para pular)
As duas perguntas no bloco de código abaixo geram um commit com mudanças significativas:
? Existem alterações significativas? ? Descreva as mudanças mais recentes:
Na seção de problemas relacionados ao commit, você pode consultar os problemas do GitHub, JIRA ou outras ferramentas semelhantes:
? Essa mudança afeta algum problema em aberto? ? Adicione referências de problemas (por exemplo,”consertar # 123″,”re # 123″.):
Depois de responder a essas solicitações de acordo com suas necessidades, você terá um commit como o mostrado abaixo:
Autor: #AUTHOR_NAME <#AUTHOR_EMAIL> Data: Mon Jul 12 21:10:17 2021 +0200 feat (some-scope): uma breve descrição uma longa descrição QUEBRANDO MUDANÇA: quebra 123
Adicionando commitlint para fazer cumprir as regras
Para garantir que todos os desenvolvedores em nosso projeto sigam as mesmas convenções, usaremos git hooks com Husky e commitlint.
Instalando as ferramentas necessárias
Primeiro, vamos instalar o commitlint e o Husky executando o bloco de código abaixo:
# Instalar commitlint cli e configuração convencional npm install–save-dev @ commitlint/config-convencional @ commitlint/cli # Instalar Husky npm install husky–save-dev
Configurar commitlint
Para configurar o commitlint, precisaremos criar um arquivo de configuração denominado commitlint.config.js e adicione o seguinte devido ao código:
module.exports={extends: [‘@ commitlint/config-convencional’]}
Para lint as mensagens antes de serem confirmadas, precisamos usar o gancho commit-msg do Husky executando o seguintes comandos:
# Activate hooks npx husky install # Adicionar hook npx husky add.husky/commit-msg’npx–no-install commitlint–edit”$ 1″‘
Você pode adicionar a instalação husky como um npm prepare script, entretanto, esta etapa é opcional. a instalação husky garantirá que todos os desenvolvedores que usam este repo instalem o Husky Hooks antes de usar o projeto:
…”scripts”: {…”prepare”:”husky install”}
Continuaremos use git commit para fazer nossos commits seguirem a convenção descrita anteriormente. Se houver um erro na mensagem git, commitlint gerará os seguintes erros:
git commit-m”Este é um commit”⧗ input: Este é um commit ✖ o assunto não pode estar vazio [subject-empty] ✖ o tipo não pode estar vazio [tipo vazio] ✖ foram encontrados 2 problemas, 0 avisos ⓘ Obtenha ajuda: \ [https://github.com/conventional-changelog/commitlint/#what-is-commitlint \] (https://github.com/conventional-changelog/commitlint/#what-is-commitlint) husky-gancho commit-msg encerrado com código 1 (erro)
Fluxo de trabalho final para gerenciamento de lançamentos
Para gerenciar seus lançamentos, você pode seguir o fluxo de trabalho listado abaixo:
Crie seus recursos e os comprometa. Se as mensagens de confirmação não estiverem seguindo a convenção, commitlint gerará erros Execute o npm run commit na linha de comando para fazer um commit com Commitizen Execute npm run release para criar um log de mudanças e uma versão baseada em versão semântica
Para criar uma versão usando CI/CD, veja a versão semântica .
Resumo
Neste post, você aprendeu como criar um changelog automático e uma versão semântica baseada em versionamento usando git hooks e Node.js. Criamos nossa mensagem de commit usando a especificação Conventional Commits, e então a liberamos usando commitizen e liberação padrão. Em seguida, usamos commitlint e Husky para escrever nosso commit automaticamente.
