30/04/2020
Commits Semânticos
A especificação do Conventional Commits é uma convenção simples para utilizar nas mensagens de commit. Ela define um conjunto de regras para criar um histórico de commit explícito, o que facilita a criação de ferramentas automatizadas.
Commit semântico ou conventional commit, em sua especificação formal, é uma das formas que a gente pode fazer padronização de commits dentro do nosso projeto utilizando de regras bem simples, que apesar de introduzirem um pouco de overhead, ele é ainda menor quando utilizando ferramentas como commitzen e git blame no seu editor. Essa padronização vai contribuir para que reduzamos o tempo gasto em compreender como e por que algo foi feito apenas olhando pelo histórico do git.
Os Tipos se resumem em feat, fix, refactor, style, chore, doc e test
- feat são quaisquer adições ao código. Enquanto elas podem alterar parte do código já existente, o foco dela é a implementação de features novas ao ecossistema.
- fix refere-se às correções de bugs. Caso seu time trabalhe com issues ou com Jira, é possível com smart commits associar seu commit a uma issue e alterar seu estado com keywords como resolve, fix, solves. Em geral, essas marcações devem vir na descrição ou no footer.
- refactor refere-se a quaisquer mudanças que atinjam o código, porém não alterem sua funcionalidade. Alterou o formato de como é processamento em determinada parte da sua tela, mas manteve a mesma funcionalidade? Declare como refactor.
- Alterações referentes a formatações de código, semicolons, trailing spaces e lint em geral são em style.
- Em uma das equipes com que trabalho, decidimos por criar novos dois tipos e ignorar o tipo chore porque ele não passava a ideia que precisávamos e passamos a utilizar outros dois: env e project. Vale notar que esses dois tipos fogem das especificações do conventional commit. Em project, todo o escopo de versões e pacotes ficam inseridos nele. Já o env, utilizamos para as funções restantes do antigo chore, como atualizações de arquivos de CI, docker, build files, tasks runners ou configurações.
- Com doc, temos conteúdo relativo à documentação.
-
Commits com tipo test estão relacionados às modificações e adições aos testes.
Especificação
As palavras-chaves “DEVE” (“MUST”), “NÃO DEVE” (“MUST NOT”), “OBRIGATÓRIO” (“REQUIRED”), “DEVERÁ” (“SHALL”), “NÃO DEVERÁ” (“SHALL NOT”), “PODEM” (“SHOULD”), “NÃO PODEM” (“SHOULD NOT”), “RECOMENDADO” (“RECOMMENDED”), “PODE” (“MAY”) e “OPCIONAL” (“OPTIONAL”), nesse documento, devem ser interpretados como descrito na RFC 2119.
- A mensagem de commit DEVE ser prefixado com um tipo, que consiste em um substantivo, feat,fix, etc., seguido por um escopo OPCIONAL, e OBRIGATÓRIO terminar com dois-pontos e um espaço.
- O tipo feat DEVE ser usado quando um commit adiciona um novo recurso ao seu aplicativo ou biblioteca.
- O tipo fix DEVE ser usado quando um commit representa a correção de um problema em seu aplicativo ou biblioteca.
- Um escopo PODE ser fornecido após um tipo. Um escopo DEVE consistir em um substantivo que descreve uma seção da base de código entre parênteses, por exemplo, fix(parser):
- Uma descrição DEVE existir depois do espaço após o prefixo tipo/escopo. A descrição é um breve resumo das alterações de código, por exemplo, fix: problema na interpretação do array quando uma string tem vários espaços.
- Um corpo de mensagem de commit mais longo PODE ser fornecido após a descrição curta, fornecendo informações contextuais adicionais sobre as alterações no código. O corpo DEVE começar depois de uma linha em branco após a descrição.
- Um rodapé de uma ou mais linhas PODE ser fornecido depois de uma linha em branco após o corpo. O rodapé DEVE conter informações adicionais sobre o commit, por exemplo, pull-requests, revisores, modificações que quebram a compatibilidade, com uma informação adicional por linha.
- A modificação que quebra a compatibilidade DEVE ser indicadas logo no início da seção do corpo ou no início de uma linha na seção de rodapé. Uma modificação que quebra a compatibilidade DEVE consistir de um texto em maiúsculas BREAKING CHANGE, seguido por dois-pontos e um espaço.
- Uma descrição DEVE ser fornecida após o texto “BREAKING CHANGE:“, descrevendo o que mudou na API, por exemplo, BREAKING CHANGE: as variáveis de ambiente agora têm preferência sobre os arquivos de configuração.
- Além de feat e fix, outro tipo PODE ser usados em suas mensagens de commit.
- Cada bloco de informação que compõem o commit convencional NÃO DEVE ser tratado como sensível a maiúscula e minúscula pelos implementadores, com exceção de BREAKING CHANGE, que DEVE ser maiúscula.
- Um ! PODE ser acrescentado antes do : no prefixo tipo/escopo, para chamar a atenção para modificações que quebram a compatibilidade. BREAKING CHANGE: description também DEVE ser incluído no corpo ou no rodapé, junto com o ! no prefixo.
Referências
https://www.conventionalcommits.org/pt-br
https://blog.cubos.io/que-tal-comecar-a-usar-commits-semanticos/
https://www.freecodecamp.org/news/writing-good-commit-messages-a-practical-guide/
https://github.com/commitizen/cz-cli
