@govbr-ds/commitlint-config 4.6.1 → 5.0.0

package/README.md

@@ -1,82 +1,218 @@
-# GovBR-DS - Commit Config
+# GovBR-DS - Commitlint Config
 
 ## Objetivo
 
-Compartilhar os padrões de commit entre os projetos do [GovBR-DS](https://gitlab.com/govbr-ds 'GovBR-DS').
+Compartilhar uma convenção de commits clara e verificável entre os projetos do GovBR-DS.
 
-## Como instalar
+Além de validar o formato das mensagens, esta configuração prepara os commits para:
 
-1. Instale as seguintes dependências
+- gerar changelogs legíveis;
+- calcular versões automaticamente com Semantic Release;
+- relacionar commits a issues do GitLab;
+- explicar ao próximo desenvolvedor o contexto e o impacto da mudança.
 
-   ```bash
-   npm install --save-dev @govbr-ds/commitlint-config husky @commitlint/cz-commitlint
-   ```
+## Formato
 
-## Como configurar
+As mensagens seguem o formato do [Conventional Commits](https://www.conventionalcommits.org/pt-br/v1.0.0/):
 
-1. Crie um arquivo `.commitlintrc.js` na raiz do seu projeto e e importe a configuração:
+```text
+tipo(escopo): resumo
 
-   ```javascript
-   export default {
-     extends: ['@govbr-ds/commitlint-config'],
-   }
-   ```
+corpo opcional com contexto, causa e impacto
 
-1. Inclua o seguinte código no seu `package.json`
+rodapé opcional, como Closes #123
+```
 
-   ```json
-     "scripts": {
-       "commit": "git-cz",
-     },
-     "config": {
-       "commitizen": {
-         "path": "@commitlint/cz-commitlint"
-       }
-     }
-   ```
+Exemplo:
 
-1. Conforme a documentação do [Husky](https://github.com/typicode/husky) inclua o hook `commit-msg` com o código abaixo:
+```text
+fix(datepicker): validar data máxima antes de emitir o evento
 
-   ```bash
-   npx commitlint --edit ${1}
-   ```
+A data máxima era ignorada quando o valor vinha do teclado, permitindo um estado inválido.
 
-   E configure o `package.json` com o seguinte script:
+Closes #123
+```
 
-   ```json
-     "scripts": {
-       "prepare": "husky || true"
-     }
-   ```
+### Tipo
 
-## Como contribuir?
+Indica a intenção da mudança. Escolha o tipo pelo efeito da alteração, não pelo arquivo modificado.
 
-Antes de abrir um Merge Request tenha em mente algumas informações:
+| Tipo         | Quando usar                                              | Efeito no release               |
+| ------------ | -------------------------------------------------------- | ------------------------------- |
+| `feat`       | Nova capacidade ou comportamento compatível              | `minor`                         |
+| `fix`        | Correção de comportamento incorreto                      | `patch`                         |
+| `docs`       | Documentação, exemplos e guias                           | `patch`                         |
+| `perf`       | Melhoria de desempenho sem alterar a API                 | `patch`                         |
+| `refactor`   | Reorganização interna sem mudar comportamento            | `patch`                         |
+| `removed`    | Remoção definitiva de API ou recurso público             | `major`                         |
+| `revert`     | Reversão de uma mudança publicada                        | `minor`                         |
+| `deprecated` | Marcação de API ou recurso como obsoleto                 | Sem release automático          |
+| `build`      | Build, bundler ou dependências de desenvolvimento        | Sem release automático          |
+| `chore`      | Manutenção interna sem efeito no produto                 | Sem release automático          |
+| `ci`         | Pipelines, jobs e automações de CI                       | Sem release automático          |
+| `lint`       | Formatação e estilo sem mudança executável               | Sem release automático          |
+| `ops`        | Atividades operacionais de design ou desenvolvimento     | Sem release automático          |
+| `site`       | Site ou documentação publicada fora do pacote            | Sem release automático          |
+| `test`       | Criação ou ajuste de testes                              | Sem release automático          |
+| `wip`        | Trabalho incompleto; não deve chegar à branch de release | Sem release automático          |
+| `bump`       | Atualização manual de versão                             | Evite; prefira Semantic Release |
 
-- Esse é um projeto opensource e contribuições são bem-vindas.
-- Para facilitar a aprovação da sua contribuição, escolha um título curto, simples e explicativo para o MR, e siga os padrões da nossa [wiki](https://gov.br/ds/wiki/ 'Wiki').
-- Quer contribuir com o projeto? Confira o nosso guia [como contribuir](../../CONTRIBUTING.md 'Como contribuir?').
+Os tipos sem release continuam disponíveis para manter o histórico consistente e permitir que o changelog diferencie mudanças de produto de manutenção interna.
 
-## Reportar bugs/necessidades
+### Escopo
 
-Você pode usar as [issues](https://gitlab.com/govbr-ds/tools/govbr-ds-config-tools/-/issues/new) para nos informar os problemas que tem enfrentado ao usar nossa biblioteca ou mesmo o que gostaria que fizesse parte do projeto. Por favor use o modelo que mais se encaixa na sua necessidade e preencha com o máximo de detalhes possível.
+Indica a área alterada. Use um nome curto, específico e estável:
 
-Nos comprometemos a responder a todas as issues
+```text
+fix(button): corrigir foco após o clique
+feat(tokens): adicionar cor semântica de informação
+docs(install): explicar instalação via pnpm
+```
 
-## Precisa de ajuda?
+O escopo não deve ser `minor` ou `patch` para forçar uma versão. A versão é determinada pelo tipo e pelas breaking changes.
 
-> Por favor **não** crie issues para fazer perguntas...
+### Resumo
 
-Use nossos canais abaixo para obter tirar suas dúvidas:
+Escreva um resumo curto, objetivo e no infinitivo:
 
-- Site do GovBR-DS [http://gov.br/ds](http://gov.br/ds)
+```text
+feat: adicionar suporte a tema escuro
+fix(menu): corrigir fechamento ao pressionar Escape
+```
 
-- Usando nosso canal no discord [https://discord.gg/U5GwPfqhUP](https://discord.gg/U5GwPfqhUP)
+Evite ponto final, frases vagas e referências sem contexto como `fix: issue 123`.
 
-## Padrão de commits
+### Corpo
 
-Para mais informações sobre o padrão de commits consulte [a nossa Wiki](https://gov.br/ds/wiki/git-gitlab/guias/commit/ 'Padrão de commit').
+Use o corpo quando o título não explicar a decisão. Responda, quando fizer sentido:
+
+- qual era o problema;
+- por que ele acontecia;
+- qual comportamento foi alterado;
+- qual impacto existe para quem usa o projeto.
+
+Ao usar o `czg`, digite `|` para inserir uma quebra de linha manualmente. Se não
+for necessário separar o texto, não use esse caractere.
+
+### Issues
+
+Relacione a issue no rodapé:
+
+```text
+Closes #123
+```
+
+Use `Closes`, `Fixes` ou `Resolves` quando o commit deve fechar a issue após o merge. Use apenas `#123` quando a issue deve ser relacionada, mas permanecer aberta.
+
+### Breaking changes
+
+Uma breaking change altera ou remove um contrato que consumidores existentes dependem. Exemplos:
+
+- remover uma propriedade, evento, método ou componente;
+- tornar obrigatório um campo antes opcional;
+- mudar o formato de retorno;
+- alterar comportamento esperado de forma incompatível.
+
+Marque a mudança no cabeçalho ou no rodapé e explique como migrar:
+
+```text
+feat(api)!: tornar token obrigatório
+
+BREAKING CHANGE: o token não é mais aceito como propriedade opcional. Envie-o no cabeçalho Authorization.
+```
+
+Toda breaking change gera uma versão `major`, independentemente do tipo escolhido.
+
+No `czg`, responda que o commit é uma breaking change para abrir o campo de
+incompatibilidade e migração. Esse campo não aparece para commits compatíveis.
+
+## Instalação
+
+```bash
+pnpm add -D @govbr-ds/commitlint-config @commitlint/cli czg husky
+```
+
+O `czg` é opcional: instale-o apenas se quiser usar o prompt interativo. O
+`@commitlint/cli` é necessário para validar os commits, e o `husky` é necessário
+apenas para executar essa validação automaticamente no commit local.
+
+## Configuração
+
+Crie `.commitlintrc.js` na raiz:
+
+```javascript
+export default {
+  extends: ['@govbr-ds/commitlint-config'],
+}
+```
+
+O exemplo usa `export default`; portanto, o projeto deve usar módulos ES (`"type":
+"module"` no `package.json`). Em projetos que não usam módulos ES, utilize a
+extensão de configuração compatível com a versão do commitlint instalada.
+
+Para usar o `czg`, crie `cz.config.cjs` na raiz e reutilize a configuração
+compartilhada:
+
+```javascript
+module.exports = require('@govbr-ds/commitlint-config/czg')
+```
+
+Adicione o czg ao `package.json`:
+
+```json
+{
+  "scripts": {
+    "commit": "czg --config=./cz.config.cjs",
+    "prepare": "husky"
+  }
+}
+```
+
+Inicialize o Husky e crie o hook `.husky/commit-msg`:
+
+```bash
+pnpm exec husky init
+```
+
+No arquivo `.husky/commit-msg`, use:
+
+```bash
+pnpm exec commitlint --edit "$1"
+```
+
+Adicione o script `prepare` caso ele ainda não exista, para que o Husky seja
+configurado após a instalação das dependências:
+
+```json
+{
+  "scripts": {
+    "prepare": "husky"
+  }
+}
+```
+
+Execute `pnpm commit` (ou o script equivalente configurado no projeto) para
+abrir o prompt interativo. O `czg` reutiliza os tipos compartilhados, oferece a
+marcação de breaking change e gera a mensagem; o hook do commitlint continua
+sendo a validação obrigatória, inclusive para mensagens criadas manualmente.
+
+O hook impede mensagens inválidas no commit local. O pipeline deve executar a mesma validação para proteger commits criados sem os hooks locais.
+
+## Exemplos rápidos
+
+```text
+feat(header): adicionar navegação responsiva
+fix(input): preservar valor ao exibir mensagem de erro
+docs(tokens): explicar token de superfície
+refactor(core): separar parser de validação
+test(select): cobrir navegação por teclado
+ci: atualizar imagem do pipeline
+```
+
+## Contribuição
+
+Antes de abrir um Merge Request, consulte o guia de contribuição e mantenha esta documentação alinhada com as regras do pacote release. Alterações em tipos, regras ou impacto SemVer devem incluir exemplos de mensagens válidas e inválidas.
 
 ## Licença
 
-Nesse projeto usamos a licença MIT.
+Este projeto utiliza a licença MIT.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@govbr-ds/commitlint-config",
-  "version": "4.6.1",
+  "version": "5.0.0",
   "private": false,
   "description": "Padrão de commits para projetos do Padrão Digital de Governo",
   "keywords": [
@@ -18,17 +18,24 @@
   },
   "license": "MIT",
   "author": "SERPRO (http://serpro.gov.br/)",
+  "publishConfig": {
+    "access": "public"
+  },
   "type": "module",
   "main": "src/.commitlintrc.js",
+  "exports": {
+    ".": "./src/.commitlintrc.js",
+    "./czg": "./src/czg.cjs"
+  },
   "files": [
-    "src/.commitlintrc.js"
+    "src/.commitlintrc.js",
+    "src/czg.cjs"
   ],
   "dependencies": {
-    "@commitlint/cli": "^19.8.1",
-    "@commitlint/config-conventional": "^19.8.1",
-    "@commitlint/cz-commitlint": "^19.8.1",
-    "@commitlint/format": "^19.8.1",
-    "@commitlint/lint": "^19.8.1",
-    "commitizen": "^4.3.1"
+    "@commitlint/cli": "^21.2.1",
+    "@commitlint/config-conventional": "^21.2.0",
+    "@commitlint/format": "^21.2.0",
+    "@commitlint/lint": "^21.2.0",
+    "@govbr-ds/commit-types": "5.0.0"
   }
 }

package/src/.commitlintrc.js

@@ -1,109 +1,88 @@
+import commitTypesModule from '@govbr-ds/commit-types'
+
+const { commitTypes } = commitTypesModule
+
+const promptTypes = Object.fromEntries(
+  commitTypes.map(({ value, description, semverBump }) => [
+    value,
+    {
+      description: `${description}. ${
+        semverBump === 'none'
+          ? 'Não gera uma nova versão por conta própria.'
+          : `Gera uma nova versão do tipo ${semverBump}.`
+      }`,
+    },
+  ])
+)
+
 export default {
   defaultIgnores: true,
   extends: ['@commitlint/config-conventional'],
   formatter: '@commitlint/format',
   helpUrl: 'https://gov.br/ds/wiki/git-gitlab/guias/commit/',
   ignores: [(commit) => commit.includes('[skip ci]')],
+
   prompt: {
     messages: {
-      emptyWarning: 'Item obrigatório. Por favor preencha conforme orientação.',
-      lowerLimitWarning: 'Abaixo do limite de caracteres',
-      max: 'Máximo de %d caracteres',
-      min: 'Mínimo de %d caracteres',
-      skip: '(OPCIONAL)',
-      upperLimitWarning: 'Acima do limite de caracteres',
+      emptyWarning: 'Este campo é obrigatório. Preencha-o conforme a orientação.',
+      lowerLimitWarning: 'O conteúdo está abaixo do número mínimo de caracteres.',
+      max: 'Use no máximo %d caracteres.',
+      min: 'Use pelo menos %d caracteres.',
+      skip: '(opcional)',
+      upperLimitWarning: 'O conteúdo ultrapassa o número máximo de caracteres.',
     },
+
     questions: {
       body: {
-        description: 'Descrição DETALHADA da mudança (Use \\n para quebrar linhas)',
+        description: 'Explique o contexto, a motivação e o impacto da mudança. Use \\n para inserir quebras de linha.',
       },
+
       breaking: {
-        description: 'Descrição BREVE da(s) BREAKING CHANGE(S)',
+        description: 'Resuma a mudança incompatível e informe quais consumidores precisarão adaptar o código.',
       },
+
       breakingBody: {
         description:
-          'A descrição DETALHADA é obrigatória para BREAKING CHANGE(S). Descreva EM DETALHES a mudança. (Use \\n para quebrar linhas)',
+          'Descreva o comportamento anterior, o novo comportamento e as etapas necessárias para migração. Use \\n para inserir quebras de linha.',
       },
+
       isBreaking: {
-        description: 'Existe BREAKING CHANGE?',
+        description: 'Esta mudança quebra a compatibilidade com versões anteriores?',
       },
+
       isIssueAffected: {
-        description: 'Essa mudança relaciona/fecha alguma(s) issue(s)?',
+        description: 'Este commit está relacionado a uma issue ou deve encerrá-la?',
       },
+
       issues: {
-        description:
-          'Liste a(s) issue(s) (Veja https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically)',
+        description: 'Informe as issues relacionadas. Exemplos: #123, Closes #123 ou Fixes #123.',
       },
+
       issuesBody: {
         description:
-          'A descrição DETALHADA é obrigatória quando um commit relaciona/fecha uma issue. Descreva EM DETALHES a mudança. (Use \\n para quebrar linhas)',
+          'Explique como este commit atende à issue e quais pontos foram resolvidos. Use \\n para inserir quebras de linha.',
       },
+
       scope: {
-        description: 'Qual é o escopo dessa mudança? (ex: button, table, package.json)',
+        description:
+          'Informe a área afetada usando um nome curto, específico e estável. Exemplos: button, table ou package.json.',
       },
+
       subject: {
-        description: 'Descrição BREVE sobre a mudança (Veja https://gov.br/ds/wiki/git-gitlab/guias/commit/)',
+        description:
+          'Descreva objetivamente a mudança no infinitivo, sem ponto final e sem repetir o tipo. Exemplo: adicionar estado loading.',
       },
+
       type: {
         description:
-          'ANTES DE ENVIAR UM COMMIT, LEIA A NOSSA DOCUMENTAÇÃO SOBRE O ASSUNTO: https://gov.br/ds/wiki/git-gitlab/guias/commit/\n\n Selecione o tipo da mudança',
-        enum: {
-          build: {
-            description: 'Mudanças no sistema de build (ex: npm, node, webpack, vite...)',
-          },
-          bump: {
-            description: 'Commit sem alterações, apenas atualização de versão',
-          },
-          chore: {
-            description: 'Alterações diversas que não se encaixam em outros tipos',
-          },
-          ci: {
-            description: 'Alterações nos arquivos e scripts de configuração de ambiente (Gitlab, Pipelines, Permissões...)',
-          },
-          deprecated: {
-            description: 'Marca o recurso como obsoleto. Provavelmente será removido em uma próxima versão',
-          },
-          docs: {
-            description: 'Atividades de documentação (tutorial, guia, etc...)',
-          },
-          feat: {
-            description: 'Nova feature, recurso, elemento, comportamento, etc...',
-          },
-          fix: {
-            description: 'Correção em feature, recurso, elemento, comportamento, etc...',
-          },
-          lint: {
-            description: 'Mudanças que não alteram o significado/comportamento (espaços, formatação, semi-vírgulas ausentes...)',
-          },
-          ops: {
-            description: 'Atividades operacionais relacionadas a design e desenvolvimento',
-          },
-          perf: {
-            description: 'Melhoria de desempenho (tempo de execução, tamanho, carregamento...)',
-          },
-          refactor: {
-            description: 'Altera o conteúdo sem mudar o resultado final (ex: organização de pastas, camadas...)',
-          },
-          removed: {
-            description: 'Recurso excluído definitivamente do projeto',
-          },
-          revert: {
-            description: 'Reverte um commit',
-          },
-          site: {
-            description: 'Alterações relacionadas ao site ou documentação online',
-          },
-          test: {
-            description: 'Atividades relacionadas a testes',
-          },
-          wip: {
-            description: 'Trabalho ainda não finalizado',
-          },
-        },
+          'Escolha o tipo que melhor representa a intenção da mudança. Ele pode influenciar o changelog e a próxima versão.',
+        enum: promptTypes,
       },
     },
   },
-  // https://commitlint.js.org/#/reference-rules
+
+  // Estas regras validam apenas o formato da mensagem.
+  // O impacto no SemVer é definido por commitTypes e pelo release-config.
   rules: {
     'body-full-stop': [0, 'always', '.'],
     'body-leading-blank': [2, 'always'],
@@ -122,29 +101,7 @@ export default {
     'subject-full-stop': [0, 'always', '.'],
     'subject-max-length': [0, 'always', Infinity],
     'type-case': [0, 'always', 'lower-case'],
-    'type-enum': [
-      2,
-      'always',
-      [
-        'build',
-        'bump',
-        'chore',
-        'ci',
-        'deprecated',
-        'docs',
-        'feat',
-        'fix',
-        'lint',
-        'ops',
-        'perf',
-        'refactor',
-        'removed',
-        'revert',
-        'site',
-        'test',
-        'wip'
-      ],
-    ],
+    'type-enum': [2, 'always', commitTypes.map(({ value }) => value)],
     'type-max-length': [2, 'always', Infinity],
   },
 }

package/src/czg.cjs

@@ -0,0 +1,22 @@
+const { commitTypes } = require('@govbr-ds/commit-types')
+
+module.exports = {
+  types: commitTypes.map(({ value, description }) => ({
+    value,
+    name: `${value}: ${description}`,
+  })),
+  messages: {
+    type: 'Selecione o tipo que melhor representa a intenção da mudança:',
+    scope: 'Informe a área, o componente ou o arquivo afetado (opcional):',
+    subject: 'Resuma objetivamente a mudança no infinitivo e sem ponto final:',
+    body: 'Explique o contexto, a motivação e o impacto da mudança (opcional; use | para quebrar linha):',
+    breaking:
+      'Descreva a incompatibilidade introduzida e as etapas necessárias para migração (use | para quebrar linha):',
+    footer: 'Informe issues relacionadas, referências ou outros metadados (opcional):',
+    confirmCommit: 'Deseja confirmar esta mensagem de commit?',
+  },
+  markBreakingChangeMode: true,
+  // czg usa Infinity para quebrar o texto palavra por palavra. Este limite alto
+  // mantém a formatação em uma linha na prática sem limitar a validação.
+  breaklineNumber: 1000,
+}