Git Flow

Convenções de branches, commits e processo de contribuição do fast_deliv.

Estrutura de Branches

main (protegido — sempre deployável em produção)
  └── develop (integração — deploy automático em preview)
        ├── feat/nome-da-feature
        ├── fix/nome-do-bug
        ├── chore/nome-da-tarefa
        ├── refactor/nome-do-refactor
        ├── docs/nome-da-documentacao
        └── test/nome-do-teste

`main`

Branch de produção
Protegida: requer PR + aprovação + CI verde
Deploy automático na Vercel ao fazer merge

`develop`

Branch de integração
Base para criação de feature branches
Deploy automático em ambiente de preview

Feature branches

Criadas a partir de develop
Nomeadas com prefixo do tipo: feat/, fix/, chore/, etc.
Deletadas após merge

Criando uma Feature Branch

# Garantir que develop está atualizado
git checkout develop
git pull origin develop

# Criar branch de feature
git checkout -b feat/adicionar-relatorio-ganhos

# ... fazer alterações ...

# Commit (seguindo Conventional Commits)
git add backend/app/api/v1/reports.py
git commit -m "feat: adicionar endpoint de relatório de ganhos por período"

# Push
git push origin feat/adicionar-relatorio-ganhos

# Abrir Pull Request para develop
gh pr create --base develop --title "feat: relatório de ganhos" --body "..."

Conventional Commits

Todos os commits devem seguir o padrão Conventional Commits.

Formato

<tipo>(<escopo>): <descrição curta>

[corpo opcional]

[rodapé opcional]

Tipos Permitidos

Tipo	Quando Usar
`feat`	Nova funcionalidade
`fix`	Correção de bug
`chore`	Tarefas de manutenção (deps, config)
`refactor`	Refatoração sem mudança de comportamento
`test`	Adição ou correção de testes
`docs`	Apenas documentação
`perf`	Melhoria de performance
`ci`	Configuração de CI/CD
`style`	Formatação, sem mudança de lógica

Exemplos

git commit -m "feat: adicionar endpoint de cancelamento de entrega"
git commit -m "fix: corrigir validação de chave Pix tipo CPF"
git commit -m "chore: atualizar dependência httpx para 0.28.1"
git commit -m "refactor: extrair lógica de pricing para service dedicado"
git commit -m "test: adicionar testes unitários para calculate_driver_earning"
git commit -m "docs: documentar fluxo de pagamentos ASAAS"

Escopo (opcional mas recomendado)

git commit -m "feat(api): adicionar paginação em GET /deliveries"
git commit -m "fix(auth): corrigir extração de role do JWT payload"
git commit -m "feat(frontend): adicionar componente de mapa com MapLibre"

Commitlint

O repositório usa commitlint para validar mensagens automaticamente:

# Configuração em frontend/commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
}

O hook é executado antes de cada commit via Husky.

Pull Requests

Processo

Abra um PR da sua feature branch para develop
Preencha o template de PR (título, descrição, checklist)
Aguarde revisão do security-agent e test-agent (agentes de qualidade)
CI deve passar (lint, type-check, testes)
Pelo menos 1 aprovação necessária
Merge via Squash and merge (mantém histórico limpo)

Template de PR

## O que essa PR faz?
Breve descrição das mudanças.

## Tipo de mudança
- [ ] Nova feature
- [ ] Bug fix
- [ ] Refactor
- [ ] Documentação

## Checklist
- [ ] `ruff check` passa sem erros
- [ ] `mypy --strict` passa
- [ ] Testes adicionados/atualizados
- [ ] Documentação atualizada (se necessário)
- [ ] Sem `console.log` ou `print` de debug
- [ ] Sem chaves sensíveis no código

Tags e Releases

Criar release

# Após merge em main
git checkout main
git pull origin main

# Tag semântica
git tag -a v1.2.0 -m "Release v1.2.0: adicionar relatório de ganhos"
git push origin v1.2.0

# Criar release no GitHub
gh release create v1.2.0 \
  --title "v1.2.0 — Relatório de Ganhos" \
  --notes "## Novidades\n- Endpoint /api/v1/reports\n- Filtro por período"

Versionamento Semântico

MAJOR.MINOR.PATCH

MAJOR: mudanças incompatíveis na API
MINOR: novas funcionalidades compatíveis com versões anteriores
PATCH: correções de bugs

Proteções de Branch

Configure no GitHub: - main: Require PR + 1 approval + CI verde + No force push - develop: Require PR + CI verde

# Via GitHub CLI
gh repo edit --default-branch main
gh api repos/{owner}/{repo}/branches/main/protection \
  -X PUT \
  -f required_status_checks='{"strict":true,"contexts":["lint","test"]}' \
  -f enforce_admins=false \
  -f required_pull_request_reviews='{"required_approving_review_count":1}' \
  -f restrictions=null

Comandos Git Úteis

# Ver histórico limpo
git log --oneline --graph --decorate

# Atualizar branch com develop
git fetch origin
git rebase origin/develop

# Desfazer último commit (sem perder mudanças)
git reset --soft HEAD~1

# Ver diferença entre branches
git diff develop...feat/minha-feature

# Stash de mudanças temporárias
git stash push -m "WIP: experimento de pricing"
git stash pop