6

Eventualmente, quando navego por alguns dos repositórios do GitHub, deparo-me com certas mensagens de commit padronizadas:

feat(*): initiate re-write

Ou:

refactor(*): remove unwanted files

O que são essas palavras (feat, refactor...) que precedem a mensagem em si?
Existem outras, mas só citei duas delas.


Com uma breve pesquisa, consegui concluir que são mensagens de commit semânticas. Mas quais são as regras para usá-las? E como usá-las da maneira correta?

3
  • Não há uma regra de como e onde deve usar. O ideal é utilizar um padrão em todo o projeto, mas isso varia de pessoa para pessoa. O feat, por exemplo, é utilizado quando o desenvolvedor adiciona uma nova funcionalidade; Já o refactor é uma mudança no código, ou seja, uma refatoração. Eu costumo utilizar o padrão [type] | [local]* | Description, por exemplo: [feat] | [Painel Admin] | Implements the X, Y and Z functionalities.. A vantagem disso é a organização, fica muito mais fácil quando, por ventura, você utilizar o git log. Commented 9/09/2018 às 2:04
  • Obrigado, Valdeir. Era exatamente isso que queria saber. :) Commented 9/09/2018 às 3:19

2 Respostas 2

4

Os commits semânticos da forma que você descreveu foram propostos em um documento de convenções do AngularJS. Foram documentados e amplamente utilizados pelo Karma, um projeto open source de testes para JavaScript. Hoje, muitos projetos mantidos pela comunidade o utiliza, adaptando-se aos seus usos.

As guidelines recomendam o uso de tais convenções na mensagem de commit por:

  1. Geração automática do changelog
  2. Navegação facilitada no histórico do Git

O padrão de mensagem do commit semântico proposto é:

<tipo>(<escopo>): <assunto>

<corpo>

<rodapé>

Sendo <tipo> dos seguintes valores:

  1. feat: quando se trata de uma nova funcionalidade (do inglês, feature)
  2. fix: quando se trata de uma correção de bug
  3. docs: quando se faz uma alteração na documentação
  4. style: quando se trata de formatação de código
  5. refactor: quando se trata de refatoração de código em produção
  6. test: quando se adiciona ou refatora testes, sem impacto em código em produção
  7. chore: quando se adiciona ou edita tasks do Grunt, ou Webpack, também sem impacto em produção

O <escopo> é opcional, principalmente se a alteração for global, mas bons exemplos seriam init, runner, watcher, config, web-server, proxy, etc.

Para o <corpo> da mensagem de commit recomenda-se:

  1. Use a forma imperativa no presente dos verbos. Prefira "change" à "changed" ou "changes"
  2. Inclua os motivos das mudanças no código em comparação ao comportamento anterior

O <rodapé> pode ser dedicado para notas e avisos importantes, como se existem mudanças radicais no código que caibam uma nota. Por exemplo:

MUDANÇA RADICAL:
A opção `port-runner` da linha de comando mudou para `runner-port`, para que permaneça consistente com a sintaxe do arquivo de configuração.
Para migrar seu projeto, mude todos os comandos, onde você usa `--port-runner`, para `--runner-port`.

Também pode ser utilizado para integrações, como fechar issues no GitHub utilizando a mensagem de commit.

Closes #123, #456, #789

Por ser uma iniciativa open source, essas guidelines são mantidas pela comunidade e opinadas em artigos. Um dos mais influentes é o Semantic Commit Messages, do Sparkbox.

See how a minor change to your commit message style can make you a better programmer. I use a rigid commit message format, and it makes me a better programmer. You'll never again be tempted to include a bug fix and a feature in the same commit. My git log is now an easy-to-skim changelog.

Um exemplo de mensagem de commit seguindo esse padrão:

fix($compilação): testes unitários no IE9

Versões mais antigas do IE serializam HTML com tudo maiúsculo, mas o IE9 não.
Seria melhor esperar um *case insensitive*, mas o Jasmine não aceita expressões regulares.

Closes #392
MUDANÇA RADICAL: quanto ao foo.bar, foo.baz deve ser utilizado ao invés disso.
0
1

Uso em Node.js

Só acrescentando a resposta do Vinicius, para quem tem interesse em seguir as commit padronizadas usando Node.js, existe um pacote no NPM chamado git-commit-msg-linter . Este pacote faz o linter das mensagens para mantê-las no Angular Commit Message Guidelines. Vou mostrar também como personalizar as configurações das funcionalidades do pacote para permitir determinados tipos, adicionar novos tipos, mensagens de descrição de tipos e configurar tamanho máximo das mensagens de commit.

Como usar git-commit-msg-linter

Faça a instalação do pacote:

npm install git-commit-msg-linter --save-dev

Nenhuma configuração extra é necessária, basta que o git repository já esteja inicializado na pasta do projeto.

O pacote informa o formato de mensagem de commit a ser seguida:

Tradução adaptada

<type>(<scope>): <short summary>
  │       │             │
  │       │             └─⫸ Summary.
  │       │
  │       └─⫸ Commit Scope.
  |                          
  │
  └─⫸ Commit Type.: feat|fix|docs|style|refactor|test|chore|perf|ci|build|temp
  • Summary: Resumo no tempo presente. Sem letras maiúsculas. Sem ponto final no final.

  • Commit Scope: Opcional, pode ser qualquer coisa especificando o escopo da alteração de confirmação. Por exemplo $ location | $ browser | $ compile | $ rootScope | ngHref | ngClick | ngView, etc. No desenvolvimento de aplicativos, o escopo pode ser uma página, um módulo ou um componente.

  • Commit Type: São os tipos que o Vinicius mencionou, feat | fix | docs | style | refactor | test | chore | perf | ci | build | temp.

Obs: Os campos type e short summary são obrigatórios.

Temos uns exemplos:

  • Ruim: O pacote lança um erro e não faz o commit da mensagem.
$ git commit -m "Correct spelling of CHANGELOG."

O commit no formato acima não será válido e o pacote lançará um erro:

************* Invalid Git Commit Message **************
  commit message: adding git
  correct format: <type>[scope]: <subject>
  example: docs: update README to add developer tips

  type:
    feat     A new feature.
    fix      A bug fix.
    docs     Documentation only changes.
    style    Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc).
    refactor A code change that neither fixes a bug nor adds a feature.
    test     Adding missing tests or correcting existing ones.
    chore    Changes to the build process or auxiliary tools and libraries such as documentation generation.
    perf     A code change that improves performance.
    ci       Changes to your CI configuration files and scripts.
    build    Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm).
    temp     Temporary commit that won't be included in your CHANGELOG.

  scope:
    Optional, can be anything specifying the scope of the commit change.
    For example $location, $browser, $compile, $rootScope, ngHref, ngClick, ngView, etc.
    In App Development, scope can be a page, a module or a component.

  subject:
    Brief summary of the change in present tense. Not capitalized. No period at the end.

Repare que a mensagem tem ponto final (.) e começa com letra maiúscula (C).

  • Bons: Os casos abaixam são aceitos.
$ git commit -m "docs: correct spelling of CHANGELOG"
$ git commit -m "docs(CHANGELOG): correct spelling"

O pacote possui configurações padrões como os tipos aceitos e tamanho máximo da mensagem de commit (por padrão, o máximo é 100), mas isso pode ser facilmente personalizado de acordo com a necessidade do desenvolvedor. Basta criar um arquivo commitlinterrc.json e definir as regras a serem usadas pelo pacote.

Exemplo:

{
  "types": {
    "feat": "Nova funcionalidade do projeto",
    "build": "Nova build do projeto",
    "docs": "Nova documentacao do projeto",
    "testando": "Novo tipo pode ser usado",
    "temp": false,
    "chore": false
  },
  "max-len": 120,
  "debug": true
}
  • Em "types", definimos os tipos que serão aceitos no escopo type das mensagens.

  • Em "feat", por exemplo, alterei e coloquei uma descrição deste tipo que irá servir de consulta caso alguém faça um commit errado. Descrição:

    nova funcionalidade do projeto
  • Em "temp" e "chore" iguais a false, eu defino que esses tipos não podem ser usados nos commits.

  • Em "testando" eu definir um novo tipo que pode ser usado no type das mensagens, e ainda coloco uma descrição deste tipo.

  • "max-len" eu defino o novo tamanha máximo para as mensagens.

Agora, toda vez que eu escrever um commit em formato não aceito, teremos o seguinte erro no terminal:

$ git c "chore: adding gitignore file"

Repare que chore não é aceito.

Saída:

[DEBUG] config: {
  types: {
    feat: 'Nova funcionalidade do projeto',
    build: 'Nova build do projeto',
    docs: 'Nova documentacao do projeto',
    testando: 'Novo tipo pode ser usado ',
    temp: false,
    chore: false
  },
  'max-len': 120,
  debug: true
} 
[DEBUG] commit message: |chore: adding gitignore file| 
[DEBUG] type: chore, scope: undefined, subject: adding gitignore file 

  ************* Invalid Git Commit Message **************
  commit message: chore: adding gitignore file
  correct format: <type>[scope]: <subject>
  example: docs: update README to add developer tips

  type:
    feat     Nova funcionalidade do projeto
    fix      A bug fix.
    docs     Nova documentacao do projeto
    style    Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc).
    refactor A code change that neither fixes a bug nor adds a feature.
    test     Adding missing tests or correcting existing ones.
    perf     A code change that improves performance.
    ci       Changes to your CI configuration files and scripts.
    build    Nova build do projeto
    testando Novo tipo pode ser usado 

  scope:
    Optional, can be anything specifying the scope of the commit change.
    For example $location, $browser, $compile, $rootScope, ngHref, ngClick, ngView, etc.
    In App Development, scope can be a page, a module or a component.

  subject:
    Brief summary of the change in present tense. Not capitalized. No period at the end.

Repare que o "debug": true nos mostra o conteúdo do .json de configuração, além de informações adicionais prefixadas com [DEBUG].

No type, temos os tipos e as descrições que personalizamos, além das que vem por padrão.

Para maiores informações de personalização das mensagens, consulte o link do NPM.

Espero que esta resposta seja de interesse pra alguém. Eu particulamente gosto e uso este pacote pelo fato de podermos personalizar tipos, descrições, tamanho de mensagens de commit o que o torna o git bem mais amigável, ainda mais para novatos que começam a usá-lo e para equipes que desejam criar padrões próprios em seus projetos.

:)

Você deve fazer log-in para responder a esta pergunta.

Esta não é a resposta que você está procurando? Pesquise outras perguntas com a tag .