Convenção para Commits

De acordo com a documentação do Conventional Commits, commits semânticos são uma convenção simples para ser utilizada nas mensagens de commit. Essa convenção define um conjunto de regras para criar um histórico de commit explícito, o que facilita a criação de ferramentas automatizadas.

Esses commits auxiliarão você e sua equipe a entenderem de forma facilitada quais alterações foram realizadas no trecho de código que foi commitado.

Essa identificação ocorre por meio de uma palavra e emoji que identifica se aquele commit realizado se trata de uma alteração de código, atualização de pacotes, documentação, alteração de visual, teste...

Formato

O formato básico de um commit convencional é:

<tipo>[escopo opcional]: <descrição>

[corpo opcional]

[rodapé opcional]

• [escopo opcional]: Um escopo opcional que pode indicar a parte do código que foi alterada (e.g., ui, backend, api).

• <descrição>: Uma breve descrição, imperativa e no tempo presente, da mudança realizada.

• [corpo opcional]: Uma explicação mais detalhada da mudança, se necessário. Pode incluir motivação e contexto.

• [rodapé opcional]: Usado para informações adicionais como links para problemas fechados ou referências a pull requests. Exemplo: Closes #123, Related to #456.

Campos

• <tipo>: Indica o tipo de mudança que o commit representa. Exemplos:
  • feat: Uma nova funcionalidade.
  • fix: Correção de bug.
  • chore: Mudanças que não afetam o código em si (e.g., atualização de dependências).
  • docs: Mudanças na documentação.
  • style: Alterações que não afetam a lógica do código (e.g., formatação).
  • refactor: Refatorações que não alteram a funcionalidade.
  • test: Adição ou modificação de testes.
  • perf: Melhorias de desempenho.
  • ci: Mudanças em arquivos e scripts de integração contínua.
  • build: Mudanças que afetam o sistema de build ou dependências externas.
  • revert: Reversão de um commit anterior.

Escopos

• ui: Modificações na interface do usuário.
• auth: Alterações relacionadas à autenticação de usuários.
• api: Mudanças na API, como adição ou modificação de endpoints.
• database: Modificações no esquema do banco de dados ou migrações.
• service: Alterações em serviços ou lógica de negócios.
• router: Mudanças na lógica de roteamento da aplicação.
• config: Alterações em arquivos de configuração.
• middleware: Adição ou modificação de middlewares.
• docs: Atualizações ou adições de documentação.
• deps: Alterações em dependências do projeto.
• build: Modificações no processo de build.
• ci: Mudanças em scripts de integração contínua.
• test: Adição ou alteração de testes unitários ou de integração.
• style: Alterações de estilo e formatação de código.
• security: Atualizações relacionadas à segurança.
• cache: Modificações no mecanismo de cache.
• logging: Alterações ou adições no sistema de logging.
• deployment: Modificações em scripts ou configurações de deploy.
• performance: Melhorias de desempenho.
• i18n: Modificações ou adições relacionadas à internacionalização (i18n).

Exemplo de Commit

feat(ui): add dark mode option

Implemented a dark mode toggle in the user interface settings, allowing users to switch themes. This feature responds to the user's system preferences.

Closes #789

feat: add support for dark mode

feat(auth): add JWT token validation

fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Reviewed-by: Charleston Anjos
Refs: #123

Princípios Básicos

1. Adicione um tipo consistente com o título do conteúdo.
2. Recomendamos que na primeira linha deve ter no máximo 4 palavras.
3. Para descrever com detalhes, usar a descrição do commit.
4. Os commits devem ser feitos com o mínimo código possível que ainda faça sentido como uma unidade funcional. Isso ajuda a manter o histórico de commits claro e específico.
5. Os links precisam ser adicionados em sua forma mais autêntica, ou seja: sem encurtadores de link e links afiliados.
6. Cada commit deve conter apenas mudanças relacionadas a um único escopo de alteração. Por exemplo, se você está implementando autenticação com JWT em um arquivo de serviço, o commit deve conter apenas essa mudança. Não inclua modificações em arquivos de UI nesse commit, pois elas pertencem a um escopo diferente.

Benefícios

Clareza: Facilita o entendimento do histórico de commits por qualquer membro da equipe.

Automatização: Ferramentas podem gerar changelogs automaticamente, identificar tipos de mudanças (e.g., major, minor, patch) e facilitar a integração contínua.

Consistência: Mantém um padrão uniforme nas mensagens de commit, independentemente de quem está desenvolvendo.

Organização: Ao limitar os commits ao mínimo código necessário dentro de um único escopo, o histórico de commits torna-se mais organizado e fácil de revisar.desenvolvendo.

Ferramentas de Suporte

Para garantir que as mensagens de commit sigam a convenção, recomendamos o uso de ferramentas como Commitlint e Husky para verificar os commits antes que eles sejam feitos. Isso assegura que o padrão seja seguido em todos os commits do projeto.