Conventional Branch 1.1.0

Resumo

Conventional Branch é uma convenção estruturada e padronizada para nomeação de branches no Git, que visa tornar os nomes dos branches mais legíveis e acionáveis. Sugerimos alguns prefixos de branch que você pode usar, mas também é possível especificar sua própria convenção de nomes. Uma convenção consistente facilita a identificação dos branches pelo tipo.

Pontos-chave

1. Nomes de branches orientados ao propósito: cada nome de branch indica claramente seu propósito, facilitando para todos os desenvolvedores entenderem para que serve o branch.
2. Integração com CI/CD: ao usar nomes de branch consistentes, é possível auxiliar sistemas automatizados (como pipelines de integração contínua/entrega contínua) a disparar ações específicas com base no tipo de branch (como implantação automática a partir de branches de release).
3. Colaboração em equipe: incentiva a colaboração dentro das equipes ao tornar explícito o propósito do branch, reduzindo mal-entendidos e facilitando a troca de tarefas entre membros sem confusão.

Especificação

Prefixos de nomeação de branch

A especificação de branch suporta os seguintes prefixos e deve ser estruturada da seguinte forma:

<tipo>/<descrição>

Prefixos de propósito — descrevem a intenção do trabalho:

• feature/ (or feat/): para novas funcionalidades (ex.: feature/add-login-page, feat/add-login-page);
• bugfix/ (or fix/): para correções de bugs (ex.: bugfix/fix-header-bug, fix/header-bug);
• hotfix/: para correções urgentes (ex.: hotfix/correcao-seguranca);
• release/: para branches de release (ex.: release/v1.2.0); e
• chore/: para tarefas não relacionadas ao código, como atualização de dependências ou documentação (ex.: chore/atualizar-dependencias).

Prefixos de fonte de agente de IA — identificam branches gerados por agentes de codificação de IA:

Branches tronco (main, master, develop) não usam prefixo.

Regras básicas

1. Use letras minúsculas, números, hífens e pontos: sempre use letras minúsculas (a-z), números (0-9) e hífens (-) para separar palavras. Evite caracteres especiais, underlines ou espaços. Para branches de release, pontos (.) podem ser usados na descrição para representar versões (ex.: release/v1.2.0).
2. Sem hífens ou pontos consecutivos, iniciais ou finais: certifique-se de que hífens e pontos não apareçam consecutivamente (ex.: feature/novo--login, release/v1.-2.0), nem no início ou fim da descrição (ex.: feature/-novo-login, release/v1.2.0.).
3. Seja claro e conciso: o nome do branch deve ser descritivo, mas conciso, indicando claramente o propósito do trabalho.
4. Inclua o número do ticket: se aplicável, inclua o número do ticket da sua ferramenta de gestão de projetos para facilitar o rastreamento. Por exemplo, para o ticket issue-123, o nome do branch pode ser feature/issue-123-novo-login.

Gramática formal

A gramática ABNF (Augmented Backus-Naur Form) a seguir define formalmente nomes de branches válidos:

branch-name     = trunk-branch / prefixed-branch
trunk-branch    = "main" / "master" / "develop"
prefixed-branch = type "/" description
type            = "feature" / "feat" / "bugfix" / "fix"
                / "hotfix" / "release" / "chore"
                / "ai" / "copilot" / "cursor"
                / "claude" / "codex"
description     = desc-segment *("-" desc-segment)
desc-segment    = 1*(ALPHA / DIGIT) *("." 1*(ALPHA / DIGIT))
ALPHA           = %x61-7A   ; letras minúsculas a-z
DIGIT           = %x30-39   ; dígitos 0-9

Nota: Hífens ou pontos consecutivos e hífens ou pontos no início ou no final da descrição não são permitidos.

Exemplos

Conclusão

• Comunicação clara: o nome do branch por si só já fornece um entendimento claro do propósito da alteração de código.
• Amigável para automação: facilmente integrável a processos automatizados, possibilitando, por exemplo, a configuração de diferentes workflows para feature, release etc.
• Escalabilidade: funciona bem em equipes grandes, onde muitos desenvolvedores trabalham em tarefas diferentes simultaneamente.

Em resumo, o Conventional Branch foi projetado para melhorar a organização do projeto, a comunicação e a automação nos fluxos de trabalho com Git.

Ferramentas

Use estas ferramentas para adotar e aplicar Conventional Branch no seu projeto:

• commit-check: Verifique nomes de branches, mensagens de commit e metadados Git relacionados localmente.
• commit-check-action: Valide nomes de branches automaticamente no GitHub Actions.
• VSCode Conventional Branch: Crie nomes de branches Conventional Branch no Visual Studio Code.
• Conventional Branch Skill: Ensine assistentes de programação com IA a criar nomes válidos de Conventional Branch.

Instale a skill com:

npx skills add conventional-branch/conventional-branch --skill conventional-branch

Perguntas frequentes

Como o Conventional Branch se relaciona com o Conventional Commits?

O Conventional Branch foi inspirado pelo Conventional Commits e segue uma filosofia semelhante: trazer estrutura legível por humanos e máquinas para os metadados do Git. Enquanto o Conventional Commits padroniza mensagens de commit, o Conventional Branch padroniza nomes de branches. As duas especificações se complementam naturalmente.

Por que os tipos de branch não são tão detalhados quanto os Conventional Commits (por exemplo, build, ci, docs, style, refactor)?

Branches são diferentes de commits – são temporários e usados principalmente até serem mesclados. Introduzir muitos tipos de branch seria desnecessário e tornaria mais difícil gerenciá-los e lembrá-los.

Posso definir meus próprios tipos de branch além dos listados?

Sim. A especificação define um conjunto recomendado de tipos, mas equipes podem definir tipos personalizados adicionais para seu fluxo de trabalho. No entanto, é importante documentar claramente os tipos personalizados para que todos os membros da equipe e ferramentas automatizadas estejam cientes deles.

Quais são as principais diferenças entre v1.1.0 e v1.0.0?

v1.1.0 adiciona Prefixos de fonte de agente de IA como a principal nova funcionalidade (veja a próxima pergunta frequente para saber por que foram introduzidos). Também inclui um site versionado com um seletor de versão para que os usuários possam navegar pelas especificações v1.0.0 e v1.1.0. Todos os nomes de branch v1.0.0 existentes permanecem totalmente válidos — sem alterações que quebrem a compatibilidade.

Por que adicionar prefixos de fonte de agente de IA?

Agentes de codificação de IA (GitHub Copilot, Cursor, Claude Code, OpenAI Codex, etc.) são cada vez mais usados para gerar código e criar pull requests. Cada agente usa seu próprio prefixo de branch (ex.: copilot/, cursor/). Ao padronizar esses prefixos na especificação Conventional Branch, possibilitamos:

1. Identificação rápida — revisores e ferramentas podem reconhecer imediatamente PRs gerados por IA
2. Validação por ferramentas — ferramentas como commit-check podem validar branches de agentes de IA contra a especificação
3. Um padrão de registro — novos agentes de IA podem adotar um prefixo documentado em vez de inventar padrões ad-hoc

O prefixo genérico ai/ está disponível para qualquer agente de IA sem um prefixo dedicado, ou para equipes que preferem um identificador neutro em relação ao fornecedor. Esta é a principal novidade lançada na v1.1.0 — para um resumo completo das mudanças entre versões, veja a pergunta frequente acima.

Como devo lidar com branches de longa duração como develop ou staging?

Na gramática formal da especificação, apenas main, master e develop são considerados trunk-branch. Outros branches de integração ou de ambiente de longa duração (por exemplo, staging, production) podem ser adotados por cada projeto como extensões específicas da convenção, também sem prefixo, desde que sejam documentados e usados de forma consistente em todo o projeto.

Quais ferramentas podem ser usadas para identificar automaticamente se um membro da equipe não segue esta especificação?

Você pode usar o commit-check para verificar a especificação de branch ou o commit-check-action se seu código estiver hospedado no GitHub.