|
|
|
Esta página descreve o método Conventional Commits e faz parte do [Catálogo do LabES](../home).
|
|
|
|
Esta página descreve o método _Conventional Commits_ e faz parte do [Catálogo do LabES](../home).
|
|
|
|
|
|
|
|
|
|
|
|
## O que é?
|
|
|
|
|
|
|
|
O Conventional Commits (CC) é uma especificação para adicionar significado às mensagens de commit, sendo legível tanto para humanos quanto para máquinas. Ele foi inspirado e baseado no Angular Commit Guidelines, um conhecido framework Javascript. O CC é compatível com o Semantic Versioning (SemVer), que usa o formato de MAJOR.MINOR.PATCH para liberação de releases de software. Basicamente, a compatibilidade se denota na utilização de tipos de commits correspondentes ao formato do SemVer, e.g., fix (patch), feat (minor), breaking change (major).
|
|
|
|
O _Conventional Commits_ (CC) é uma especificação para adicionar significado às mensagens de _commit_ do [Git](ferramentas/git), sendo legível tanto para humanos quanto para máquinas. Ele foi inspirado e baseado no _Angular Commit Guidelines_, proposto pelos desenvolvedores de um conhecido _framework_ Javascript. O CC é compatível com o _Semantic Versioning_ ([SemVer](https://semver.org/)), que usa o formato de MAJOR.MINOR.PATCH para liberação de _releases_ de software. Basicamente, a compatibilidade se denota na utilização de tipos de _commits_ correspondentes ao formato do SemVer, e.g., _fix_ (_patch_), _feat_ (_minor_), _breaking change_ (_major_).
|
|
|
|
|
|
|
|
|
|
|
|
## Quando se aplica?
|
|
|
|
|
|
|
|
Em todos os commits efetuados por quaisquer membros da equipe. Os commits que seguem a especificação do CC tornam a "história dos commits" mais explícita através de suas regras. Ele traz padronização a partir de mensagens mais descritivas e fáceis de entender, e também aprimora a comunicação, informando a natureza da mudança para a equipe e demais interessados. Dessa forma, ele desestimula o "movimento rápido" da equipe de desenvolvimento de forma desorganizada. A partir da padronização, o CC então facilita a automatização de atividades, permitindo que CHANGELOGS e releases notes sejam gerados automaticamente a partir dos commits, além da possibilidade de disparar gatilhos específicos nas pipelines no git para executar rotinas específicas. Em linhas gerais, o CC conduz a equipe para uma melhor organização dos commits. Sua estrutura, tipos de commits e regras de uso são relativamente simples, o que permite uma rápida assimilação.
|
|
|
|
Em todos os _commits_ efetuados por quaisquer membros da equipe. Os _commits_ que seguem a especificação do CC tornam a "história dos _commits_" mais explícita através de suas regras. Ele traz padronização a partir de mensagens mais descritivas e fáceis de entender, e também aprimora a comunicação, informando a natureza da mudança para a equipe e demais interessados. Dessa forma, ele desestimula o "movimento rápido" da equipe de desenvolvimento de forma desorganizada. A partir da padronização, o CC então facilita a automatização de atividades, permitindo que _CHANGELOGS_ e _release notes_ sejam gerados automaticamente a partir dos _commits_, além da possibilidade de disparar gatilhos específicos nas _pipelines_ no [Git](ferramentas/git) para executar rotinas específicas. Em linhas gerais, o CC conduz a equipe para uma melhor organização dos _commits_. Sua estrutura, tipos de commits e regras de uso são relativamente simples, o que permite uma rápida assimilação.
|
|
|
|
|
|
|
|
|
|
|
|
## Como usar/aplicar?
|
| ... | ... | @@ -27,73 +27,79 @@ Cada mensagem de commit deve seguir a seguinte **estrutura**: |
|
|
|
|
|
|
|
Os principais **tipos de commit** são:
|
|
|
|
|
|
|
|
> `feat`: nova feature (MINOR do SemVer)
|
|
|
|
>
|
|
|
|
> `fix`: corrigir bug (PATCH do SemVer)
|
|
|
|
>
|
|
|
|
> `docs`: mudanças na documentação
|
|
|
|
>
|
|
|
|
> `refactor`: melhorar/refatorar código sem alterar a API pública/fachadas – não resolve bug nem adiciona feature
|
|
|
|
>
|
|
|
|
> `perf`: melhoria em desempenho
|
|
|
|
>
|
|
|
|
> `test`: adicionar teste para uma feature
|
|
|
|
>
|
|
|
|
> `chore`: atualizar qualquer coisa sem impactar o usuário
|
|
|
|
>
|
|
|
|
> `ci`: mudanças na configuração do processo de CI
|
|
|
|
>
|
|
|
|
> `build`: mudanças que afetam a construção do sistema (maven, dependências, etc.)
|
|
|
|
- `feat`: nova feature (MINOR do SemVer);
|
|
|
|
|
|
|
|
- `fix`: corrigir bug (PATCH do SemVer);
|
|
|
|
|
|
|
|
- `docs`: mudanças na documentação;
|
|
|
|
|
|
|
|
- `refactor`: melhorar/refatorar código sem alterar a API pública/fachadas – não resolve bug nem adiciona feature;
|
|
|
|
|
|
|
|
- `perf`: melhoria em desempenho;
|
|
|
|
|
|
|
|
- `test`: adicionar teste para uma feature;
|
|
|
|
|
|
|
|
- `chore`: atualizar qualquer coisa sem impactar o usuário;
|
|
|
|
|
|
|
|
- `ci`: mudanças na configuração do processo de CI;
|
|
|
|
|
|
|
|
- `build`: mudanças que afetam a construção do sistema (maven, dependências, etc.).
|
|
|
|
|
|
|
|
Novos tipos poderão ser adicionados pelos orientadores, caso seja necessário.
|
|
|
|
Novos tipos poderão ser adicionados pelos coordenadores dos projetos, caso seja necessário.
|
|
|
|
|
|
|
|
Atualmente, estão especificadas 16 **regras de uso do CC**:
|
|
|
|
|
|
|
|
1. _Commits_ devem ser **prefixados** com um tipo, seguido por escopo (opcional), `!` (opcional) e obrigatoriamente dois pontos e espaço (e.g., `feat: adiciona funcionalidade de matrícula do aluno`)
|
|
|
|
1. _Commits_ devem ser **prefixados** com um tipo, seguido por escopo (opcional), `!` (opcional) e obrigatoriamente dois pontos e espaço (e.g., `feat: adiciona funcionalidade de matrícula do aluno`);
|
|
|
|
|
|
|
|
2. O tipo `feat` deve ser usado quando o _commit_ adiciona uma **nova funcionalidade**
|
|
|
|
2. O tipo `feat` deve ser usado quando o _commit_ adiciona uma **nova funcionalidade**;
|
|
|
|
|
|
|
|
3. O tipo `fix` deve ser usado quando o _commit_ representa uma **correção de bug**
|
|
|
|
3. O tipo `fix` deve ser usado quando o _commit_ representa uma **correção de bug**;
|
|
|
|
|
|
|
|
4. O **escopo** é opcional. Quando usado, deve ser um **substantivo** descrevendo uma seção da base de código, com parênteses (e.g., `feat(lang): suporte ao idioma chinês`)
|
|
|
|
4. O **escopo** é opcional. Quando usado, deve ser um **substantivo** descrevendo uma seção da base de código, com parênteses (e.g., `feat(lang): suporte ao idioma chinês`);
|
|
|
|
|
|
|
|
5. A **descrição** deve ser imediatamente após dois pontos e espaço do tipo/escopo. É um resumo das mudanças realizadas (e.g., `feat: adiciona funcionalidade de matrícula do aluno`)
|
|
|
|
5. A **descrição** deve ser imediatamente após dois pontos e espaço do tipo/escopo. É um resumo das mudanças realizadas (e.g., `feat: adiciona funcionalidade de matrícula do aluno`);
|
|
|
|
|
|
|
|
6. Uma **descrição mais longa** pode ser fornecida no **corpo do commit**. Ela deve começar após uma linha em branco, depois da descrição curta, e.g.,
|
|
|
|
|
|
|
|
`feat: adiciona funcionalidade de matrícula do aluno`
|
|
|
|
```
|
|
|
|
feat: adiciona funcionalidade de matrícula do aluno
|
|
|
|
|
|
|
|
Esta funcionalidade é parte do requisito XYZ, conforme especificada no issue #N
|
|
|
|
```
|
|
|
|
|
|
|
|
7. O **corpo** do _commit_ é de forma livre. Pode conter **mais de uma linha** separada por parágrafos
|
|
|
|
7. O **corpo** do _commit_ é de forma livre. Pode conter **mais de uma linha** separada por parágrafos;
|
|
|
|
|
|
|
|
8. Um ou mais **rodapés** podem ser fornecidos após uma linha em branco do corpo do _commit_. Devem conter um `token`, seguido de `:<espaço>` ou `<espaço>#`, seguido de uma `string`, e.g.,
|
|
|
|
|
|
|
|
`feat: adiciona funcionalidade de matrícula do aluno`
|
|
|
|
```
|
|
|
|
feat: adiciona funcionalidade de matrícula do aluno
|
|
|
|
|
|
|
|
`Reviewed-by: Z`
|
|
|
|
Reviewed-by: Z
|
|
|
|
|
|
|
|
`Refs #133`
|
|
|
|
Refs #133
|
|
|
|
```
|
|
|
|
|
|
|
|
9. Um _token_ no **rodapé** deve usar `–` no lugar de espaço em branco, e.g., `Reviewed-by`, com exceção `BREAKING CHANGE`, que também pode ser usado como um `token` (ajuda a diferenciar de um parágrafo do corpo do _commit_)
|
|
|
|
9. Um _token_ no **rodapé** deve usar `–` no lugar de espaço em branco, e.g., `Reviewed-by`, com exceção `BREAKING CHANGE`, que também pode ser usado como um `token` (ajuda a diferenciar de um parágrafo do corpo do _commit_);
|
|
|
|
|
|
|
|
10. A `string` no **rodapé** pode conter novas linhas e espaços e deve terminar quando um novo par _token_/separador válido é observado
|
|
|
|
10. A `string` no **rodapé** pode conter novas linhas e espaços e deve terminar quando um novo par _token_/separador válido é observado;
|
|
|
|
|
|
|
|
11. _**Breaking changes**_ devem ser indicadas no **prefixo** de tipo/escopo do _commit_ ou no rodapé.
|
|
|
|
11. **_Breaking changes_** devem ser indicadas no **prefixo** de tipo/escopo do _commit_ ou no rodapé;
|
|
|
|
|
|
|
|
12. Caso incluída no rodapé, uma _breaking change_ deve ser caixa maiúscula `BREAKING CHANGE`, seguido de dois pontos, espaço e uma descrição, e.g,
|
|
|
|
|
|
|
|
`perf: removida a funcionalidade de matrícula do aluno na API pois o tempo de resposta estava alto`
|
|
|
|
```
|
|
|
|
perf: removida a funcionalidade de matrícula do aluno na API pois o tempo de resposta estava alto
|
|
|
|
|
|
|
|
`BREAKING CHANGE: não é mais permitida matrícula de aluno por API`
|
|
|
|
BREAKING CHANGE: não é mais permitida matrícula de aluno por API
|
|
|
|
```
|
|
|
|
|
|
|
|
13. Caso uma _**breaking change**_ seja incluída no prefixo de tipo/escopo, ela deve ser indicada por um `!` imediatamente antes de `:` . Se `!` é usado, `BREAKING CHANGE:` pode ser omitido da seção de rodapé e a **mensagem do _**commit**_** deve ser usada para **descrever** a **_breaking change_**
|
|
|
|
13. Caso uma _**_breaking change_**_ seja incluída no prefixo de tipo/escopo, ela deve ser indicada por um `!` imediatamente antes de `:` . Se `!` é usado, `BREAKING CHANGE:` pode ser omitido da seção de rodapé e a **mensagem do _commit_** deve ser usada para **descrever** a **_breaking change_**;
|
|
|
|
|
|
|
|
14. **Outros tipos** além de `feat` e `fix` podem ser usados para o _commit_ das mensagens
|
|
|
|
14. **Outros tipos** além de `feat` e `fix` podem ser usados para o _commit_ das mensagens;
|
|
|
|
|
|
|
|
15. As **unidades de informação** (tipo, escopo, descrição, corpo, etc.) do Conventional Commits **não** deve, ser tratadas como **caso sensitivo**, com exceção o `BREAKING CHANGE`
|
|
|
|
15. As **unidades de informação** (tipo, escopo, descrição, corpo, etc.) do Conventional Commits **não** deve, ser tratadas como **caso sensitivo**, com exceção o `BREAKING CHANGE`;
|
|
|
|
|
|
|
|
16. `BREAKING-CHANGE` deve ser **sinônimo** de `BREAKING CHANGE` quando usado como _**token**_ no **rodapé**
|
|
|
|
16. `BREAKING-CHANGE` deve ser **sinônimo** de `BREAKING CHANGE` quando usado como _**token**_ no **rodapé**.
|
|
|
|
|
|
|
|
### **Exemplos de uso**
|
|
|
|
|
| ... | ... | @@ -111,36 +117,36 @@ _Esse commit adiciona uma melhoria no sistema (novo idioma) no escopo de idiomas |
|
|
|
|
|
|
|
`feat(lang): adiciona suporte ao idioma francês`
|
|
|
|
|
|
|
|
- **Commit com breaking change usando !**
|
|
|
|
- **Commit com _breaking change_ usando !**
|
|
|
|
|
|
|
|
_Esse commit remove uma funcionalidade do sistema, gerando incompatibilidade com outros módulos ou sistemas de terceiros que usavam o método de pagamento por boleto._
|
|
|
|
|
|
|
|
`refactor!: remove método de pagamento por boleto`
|
|
|
|
|
|
|
|
Outros exemplos concretos podem ser encontrados no site do projeto [Electron](https://github.com/electron/electron), um framework Javascript para criar aplicações Desktop em Javascript e que também faz uso do CC.
|
|
|
|
Outros exemplos concretos podem ser encontrados no site do projeto [Electron](https://github.com/electron/electron), um _framework_ Javascript para criar aplicações _desktop_ e que também faz uso do CC.
|
|
|
|
|
|
|
|
|
|
|
|
## Perguntas frequentes
|
|
|
|
|
|
|
|
### O que é uma Breaking Change?
|
|
|
|
### O que é uma _Breaking Change_?
|
|
|
|
|
|
|
|
Uma Breaking Change é qualquer mudança no código que pode gerar alguma incompatibilidade com software de terceiros ou mesmo módulos atuais do sistema. Geralmente, elas envolvem a remoção ou alteração de API's que afetam a interface de comunicação com a outra parte, o que requer modificação também na outra parte
|
|
|
|
Uma _Breaking Change_ é qualquer mudança no código que pode gerar alguma incompatibilidade com software de terceiros ou mesmo módulos atuais do sistema. Geralmente, elas envolvem a remoção ou alteração de API's que afetam a interface de comunicação com a outra parte, o que requer modificação também na outra parte
|
|
|
|
|
|
|
|
### Os tipos do título do commit precisam ser caixa alta ou baixa?
|
|
|
|
### Os tipos do título do _commit_ precisam ser caixa alta ou baixa?
|
|
|
|
|
|
|
|
No CC, qualquer um pode ser usado. É importante ser consistente.
|
|
|
|
|
|
|
|
### O que eu faço se o commit possuir mais de um tipo?
|
|
|
|
### O que eu faço se o _commit_ possuir mais de um tipo?
|
|
|
|
|
|
|
|
Volte atrás e faça múltiplos commits sempre que possível, afinal, parte do benefício do padrão está na habilidade de nos guiar para criar commits mais organizados.
|
|
|
|
Volte atrás e faça múltiplos _commits_ sempre que possível, afinal, parte do benefício do padrão está na habilidade de nos guiar para criar _commits_ mais organizados.
|
|
|
|
|
|
|
|
### O que eu faço se eu não souber qual tipo de commit usar?
|
|
|
|
### O que eu faço se eu não souber qual tipo de _commit_ usar?
|
|
|
|
|
|
|
|
Leve a dúvida imediatamente aos orientadores.
|
|
|
|
Leve a dúvida imediatamente ao coordenador do projeto.
|
|
|
|
|
|
|
|
### O CC limita os desenvolvedores aos tipos de commit especificados por eles?
|
|
|
|
### O CC limita os desenvolvedores aos tipos de _commit_ especificados por eles?
|
|
|
|
|
|
|
|
O CC é flexível o bastante para permitir que times criem os próprios tipos de commit e alterem os existentes, caso seja necessário.
|
|
|
|
O CC é flexível o bastante para permitir que times criem os próprios tipos de _commit_ e alterem os existentes, caso seja necessário.
|
|
|
|
|
|
|
|
|
|
|
|
## Referências
|
| ... | ... | @@ -150,4 +156,6 @@ O CC é flexível o bastante para permitir que times criem os próprios tipos de |
|
|
|
|
|
|
|
## Autores(as)
|
|
|
|
|
|
|
|
- @vitorsouza. |
|
|
\ No newline at end of file |
|
|
|
- @estevaosaleme (conteúdo);
|
|
|
|
- @luanaalmeida (formatação);
|
|
|
|
- @vitorsouza (revisão). |
