Carreira10 min de leitura

Versionamento Profissional: Git Flow, Conventional Commits e CHANGELOG Automático

Git Flow vs GitHub Flow vs Trunk-Based Development. Conventional Commits com escopo, BREAKING CHANGE e rodapé. Husky + commitlint para enforcement, e Release Please para CHANGELOG automático e SemVer.

12 de agosto de 2026

"Ajuste", "fix", "corrigindo bug", "WIP", "alterações" — esses commits são inúteis para qualquer pessoa além de quem os escreveu, e inúteis até para eles mesmos 3 meses depois. Em um projeto com 10 desenvolvedores por 2 anos, o histórico do Git é o único documento que descreve fielmente a evolução do sistema. Um histórico bem estruturado permite entender por que uma decisão foi tomada, fazer git bisect para encontrar quando um bug foi introduzido, e gerar CHANGELOGs automaticamente.

Este artigo cobre as três camadas do versionamento profissional: estratégia de branches (quando usar Git Flow vs GitHub Flow), Conventional Commits (como escrever mensagens semânticas) e automação (enforcement via Husky/commitlint e CHANGELOG via Release Please).

Estratégias de Branch: Escolha a Certa

Git Flow — branches main, develop, feature/*, release/*, hotfix/*. Para projetos com releases programadas e múltiplas versões em produção simultaneamente (ex: software desktop, libs públicas). Mais complexo, mais controle.
GitHub Flow — branches main + feature/*. PR direto para main. Para SaaS com deploy contínuo — mais simples, mais rápido. A maioria das equipes de produto usa isso.
Trunk-Based Development — todos commitam diretamente em main com feature flags. Para equipes muito maduras com CI/CD robusto. Maximiza velocidade de integração.

Para a maioria dos projetos web, o GitHub Flow é o ponto ideal: feature/nome-da-feature ramifica de main, PR com code review, merge com squash, deploy automático do main.

Git Flow Completo (Para Projetos com Releases)

bash

1# Branches permanentes:
# Branches permanentes:
2# main     → produção (tags de versão aqui)
# main     → produção (tags de versão aqui)
3# develop  → integração (staging/homologação)
# develop  → integração (staging/homologação)
4

5# Fluxo de uma nova feature:
# Fluxo de uma nova feature:
6git checkout develop
git checkout develop
7git checkout -b feature/user-export-csv
git checkout -b feature/user-export-csv
8# ... trabalho ...
# ... trabalho ...
9git commit -m "feat(users): adiciona exportação de usuários em CSV"
git commit -m "feat(users): adiciona exportação de usuários em CSV"
10git push origin feature/user-export-csv
git push origin feature/user-export-csv
11# Abre PR: feature/user-export-csv → develop
# Abre PR: feature/user-export-csv → develop
12# Após code review e aprovação: merge (squash ou merge commit)
# Após code review e aprovação: merge (squash ou merge commit)
13

14# Release:
# Release:
15git checkout develop
git checkout develop
16git checkout -b release/1.2.0
git checkout -b release/1.2.0
17# Apenas bugfixes nesta branch — não entra feature nova
# Apenas bugfixes nesta branch — não entra feature nova
18git commit -m "fix: corrige formatação do CSV no Windows"
git commit -m "fix: corrige formatação do CSV no Windows"
19git checkout main && git merge release/1.2.0 --no-ff
git checkout main && git merge release/1.2.0 --no-ff
20git tag v1.2.0
git tag v1.2.0
21git checkout develop && git merge release/1.2.0 --no-ff
git checkout develop && git merge release/1.2.0 --no-ff
22git branch -d release/1.2.0
git branch -d release/1.2.0
23

24# Hotfix (bug urgente em produção):
# Hotfix (bug urgente em produção):
25git checkout main
git checkout main
26git checkout -b hotfix/1.2.1
git checkout -b hotfix/1.2.1
27git commit -m "fix(auth): corrige bypass de autenticação em edge case"
git commit -m "fix(auth): corrige bypass de autenticação em edge case"
28git checkout main && git merge hotfix/1.2.1 --no-ff
git checkout main && git merge hotfix/1.2.1 --no-ff
29git tag v1.2.1
git tag v1.2.1
30git checkout develop && git merge hotfix/1.2.1 --no-ff
git checkout develop && git merge hotfix/1.2.1 --no-ff
31git branch -d hotfix/1.2.1
git branch -d hotfix/1.2.1

Conventional Commits: A Especificação Completa

Estrutura do Conventional Commit

1<tipo>(<escopo opcional>): <descrição breve>
<tipo>(<escopo opcional>): <descrição breve>
2

3[corpo opcional — por que a mudança foi feita]
[corpo opcional — por que a mudança foi feita]
4

5[rodapé opcional]
[rodapé opcional]
6Closes #123
Closes #123
7Co-authored-by: Maria Silva <maria@empresa.com>
Co-authored-by: Maria Silva <maria@empresa.com>
8BREAKING CHANGE: <descrição da quebra de compatibilidade>
BREAKING CHANGE: <descrição da quebra de compatibilidade>

feat — nova funcionalidade. Dispara Minor version no SemVer (1.1.0 → 1.2.0)
fix — correção de bug. Dispara Patch version (1.2.0 → 1.2.1)
docs — apenas documentação. Sem bump de versão.
style — formatação, espaços, ponto e vírgula. Sem bump.
refactor — reestruturação sem mudar comportamento. Sem bump.
perf — melhoria de performance. Patch version.
test — adição ou correção de testes. Sem bump.
build — mudanças no sistema de build, dependências (npm, webpack). Sem bump.
ci — mudanças em arquivos e scripts de CI (GitHub Actions, Jenkins). Sem bump.
chore — tarefas de manutenção diversas. Sem bump.
BREAKING CHANGE (no rodapé) — quebra de compatibilidade. Dispara Major version (1.2.1 → 2.0.0)

Exemplos reais de commits

1# Feature com escopo
# Feature com escopo
2git commit -m "feat(auth): adiciona login via Google OAuth2"
git commit -m "feat(auth): adiciona login via Google OAuth2"
3

4# Fix com issue reference
# Fix com issue reference
5git commit -m "fix(orders): corrige cálculo de frete para zonas rurais
git commit -m "fix(orders): corrige cálculo de frete para zonas rurais
6

7O cálculo anterior não considerava o código de zona de entrega rural
O cálculo anterior não considerava o código de zona de entrega rural
8(CEP terminado em 000). A API dos Correios retornava erro 422 nesses casos.
(CEP terminado em 000). A API dos Correios retornava erro 422 nesses casos.
9

10Closes #247"
Closes #247"
11

12# Breaking change: Major version bump
# Breaking change: Major version bump
13git commit -m "feat(api)!: renomeia endpoint /users/:id/profile para /profiles/:userId
git commit -m "feat(api)!: renomeia endpoint /users/:id/profile para /profiles/:userId
14

15ANTERORM: GET /api/users/:id/profile
ANTERORM: GET /api/users/:id/profile
16NOVO: GET /api/profiles/:userId
NOVO: GET /api/profiles/:userId
17

18BREAKING CHANGE: todos os clientes da API precisam atualizar as URLs.
BREAKING CHANGE: todos os clientes da API precisam atualizar as URLs.
19Documentação de migração em MIGRATION.md.
Documentação de migração em MIGRATION.md.
20

21Closes #198"
Closes #198"
22

23# Chore: sem bump de versão
# Chore: sem bump de versão
24git commit -m "chore(deps): atualiza TypeScript para 5.5 e corrige type errors"
git commit -m "chore(deps): atualiza TypeScript para 5.5 e corrige type errors"
25

26# Performance
# Performance
27git commit -m "perf(db): adiciona índice composto em (user_id, created_at) na tabela orders
git commit -m "perf(db): adiciona índice composto em (user_id, created_at) na tabela orders
28

29REDUZ query de listagem de pedidos de 850ms para 12ms no p99.
REDUZ query de listagem de pedidos de 850ms para 12ms no p99.
30Ver análise completa em docs/performance/orders-index.md"
Ver análise completa em docs/performance/orders-index.md"

Enforcement: Husky + commitlint

Padrões sem enforcement são apenas sugestões. Configure o commitlint para rejeitar commits fora do padrão automaticamente:

bash

1npm install --save-dev husky @commitlint/cli @commitlint/config-conventional
npm install --save-dev husky @commitlint/cli @commitlint/config-conventional
2

3# Inicializa o Husky
# Inicializa o Husky
4npx husky init
npx husky init

commitlint.config.js

1/** @type {import('@commitlint/types').UserConfig} */
/** @type {import('@commitlint/types').UserConfig} */
2module.exports = {
module.exports = {
3  extends: ['@commitlint/config-conventional'],
  extends: ['@commitlint/config-conventional'],
4  rules: {
  rules: {
5    // Tipos permitidos na sua equipe
    // Tipos permitidos na sua equipe
6    'type-enum': [
    'type-enum': [
7      2, // 2 = error (falha o commit)
      2, // 2 = error (falha o commit)
8      'always',
      'always',
9      ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert'],
      ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert'],
10    ],
    ],
11    'subject-case': [2, 'never', ['start-case', 'pascal-case', 'upper-case']],
    'subject-case': [2, 'never', ['start-case', 'pascal-case', 'upper-case']],
12    'subject-max-length': [2, 'always', 100],
    'subject-max-length': [2, 'always', 100],
13    'body-max-line-length': [2, 'always', 120],
    'body-max-line-length': [2, 'always', 120],
14    'scope-case': [2, 'always', 'lower-case'],
    'scope-case': [2, 'always', 'lower-case'],
15  },
  },
16};
};

commit-msg

1#!/usr/bin/env sh
#!/usr/bin/env sh
2. "$(dirname -- "$0")/_/husky.sh"
. "$(dirname -- "$0")/_/husky.sh"
3

4# Valida a mensagem do commit contra as regras do commitlint
# Valida a mensagem do commit contra as regras do commitlint
5npx --no -- commitlint --edit "$1"
npx --no -- commitlint --edit "$1"

package.json

1{
{
2  "scripts": {
  "scripts": {
3    "prepare": "husky"
    "prepare": "husky"
4  }
  }
5}
}
6

7// Após npm install, o Husky instala os hooks automaticamente.
// Após npm install, o Husky instala os hooks automaticamente.
8// Qualquer commit fora do padrão é rejeitado antes de ser criado:
// Qualquer commit fora do padrão é rejeitado antes de ser criado:
9// ✖ type must be one of [feat, fix, ...] [type-enum]
// ✖ type must be one of [feat, fix, ...] [type-enum]
10// ✖ subject may not be empty [subject-empty]
// ✖ subject may not be empty [subject-empty]

CHANGELOG Automático com Release Please

O Release Please (Google) lê o histórico de Conventional Commits, determina o próximo número de versão SemVer automaticamente, e cria um PR com CHANGELOG gerado. Quando você dá merge no PR, ele cria a tag e a GitHub Release:

release.yml

1name: Release Please
name: Release Please
2

3on:
on:
4  push:
  push:
5    branches: [main]
    branches: [main]
6

7permissions:
permissions:
8  contents: write
  contents: write
9  pull-requests: write
  pull-requests: write
10

11jobs:
jobs:
12  release-please:
  release-please:
13    runs-on: ubuntu-latest
    runs-on: ubuntu-latest
14    steps:
    steps:
15      - uses: googleapis/release-please-action@v4
      - uses: googleapis/release-please-action@v4
16        with:
        with:
17          token: ${{ secrets.GITHUB_TOKEN }}
          token: ${{ secrets.GITHUB_TOKEN }}
18          release-type: node
          release-type: node

release-please-config.json

1{
{
2  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
3  "release-type": "node",
  "release-type": "node",
4  "packages": {
  "packages": {
5    ".": {}
    ".": {}
6  },
  },
7  "changelog-sections": [
  "changelog-sections": [
8    { "type": "feat",     "section": "✨ Funcionalidades" },
    { "type": "feat",     "section": "✨ Funcionalidades" },
9    { "type": "fix",      "section": "🐛 Correções" },
    { "type": "fix",      "section": "🐛 Correções" },
10    { "type": "perf",     "section": "⚡ Performance" },
    { "type": "perf",     "section": "⚡ Performance" },
11    { "type": "refactor", "section": "♻️ Refatorações", "hidden": true },
    { "type": "refactor", "section": "♻️ Refatorações", "hidden": true },
12    { "type": "chore",    "section": "🔧 Manutenção",   "hidden": true }
    { "type": "chore",    "section": "🔧 Manutenção",   "hidden": true }
13  ]
  ]
14}
}

O Release Please cria um PR chamado "chore: release 1.3.0" com o CHANGELOG atualizado. Você revisa, aprova e faz o merge quando estiver pronto para o release. Isso separa o momento do commit da decisão de fazer o release — ideal para equipes que precisam de aprovação antes de publicar.

Conclusão

Conventional Commits transforma o histórico do Git de uma sequência de mensagens aleatórias em uma linha do tempo semântica e legível por máquinas. O Husky garante que ninguém da equipe pule o padrão. O Release Please elimina o trabalho manual de escrever CHANGELOGs e determinar versões. O resultado é um fluxo de release totalmente auditável, automatizado e previsível.