Git Workflow

Padrões de desenvolvimento que garantem rastreabilidade, histórico limpo e automação eficiente no projeto BITIO.

Fluxo de Trabalho (Git Flow Simplificado)

O BITIO usa um Git Flow simplificado otimizado para equipes ágeis:

gitgraph
    commit id: "Initial"
    branch develop
    checkout develop
    commit id: "Setup"
    
    branch feature/menu-api
    checkout feature/menu-api
    commit id: "Add endpoints"
    commit id: "Add tests"
    
    checkout develop
    merge feature/menu-api
    commit id: "Integration"
    
    checkout main
    merge develop
    commit id: "Release v1.0.0"
    tag: "v1.0.0"

Branches Principais

Branch	Propósito	Proteção	Deploy
main	Código estável em produção	✅ Protected	Auto → Production
develop	Integração e validação	✅ Protected	Auto → Staging
feature/*	Desenvolvimento de funcionalidades	-	Manual review

Regra Fundamental

Nunca commitar diretamente em main ou develop. Todo código passa por Pull Request com review obrigatório.

Nomenclatura de Branches

Feature Branches

feature/[ID-DA-TAREFA]-[descricao-em-ingles]

Componentes:

• ID-DA-TAREFA: Identificador do task manager (GitHub Issue, Jira, etc.)
• Descrição: Curta, minúsculas, hífens, inglês

Exemplos Válidos

feature/123-add-menu-crud-endpoints
feature/456-implement-jwt-authentication  
feature/789-fix-reservation-conflict-validation
feature/101-setup-prisma-migrations

Outros Tipos de Branch

Tipo	Formato	Exemplo
Hotfix	hotfix/[issue]-[description]	hotfix/999-fix-critical-memory-leak
Release	release/v[version]	release/v1.2.0
Chore	chore/[description]	chore/update-dependencies

Padrão de Commits (Conventional Commits)

Seguimos o padrão Conventional Commits para automação de changelog e versionamento.

Estrutura

<tipo>(<escopo>): [ID-TAREFA] descrição concisa em inglês

[Corpo opcional com mais detalhes]

[Rodapé opcional com breaking changes ou closes]

Tipos Padronizados

Tipo	Uso	Impacto no Versionamento
feat	Nova funcionalidade	MINOR version bump
fix	Correção de bug	PATCH version bump
docs	Alterações na documentação	Patch
style	Formatação, espaços, lint	Patch
refactor	Mudança de código sem alterar comportamento	Patch
test	Adicionar/modificar testes	Patch
chore	Build, dependências, config	Patch
perf	Melhoria de performance	Patch
ci	Configuração de CI/CD	Patch

Escopos Sugeridos

Escopo	Descrição	Exemplos
api	Endpoints e handlers Lambda	feat(api): add coupon generation endpoint
frontend	Interface e componentes	feat(frontend): add menu grid component
database	Migrations e schemas	feat(database): add reservation table
auth	Autenticação e autorização	fix(auth): resolve JWT validation issue
deploy	Infrastructure e CI/CD	chore(deploy): update terraform modules
docs	Documentação	docs(api): add endpoint examples

Exemplos Práticos

# ✅ Feature com escopo
feat(api): [#123] add menu CRUD endpoints with validation

# ✅ Bug fix
fix(auth): [#456] resolve JWT expiration handling

# ✅ Breaking change
feat(database): [#789] migrate to new reservation schema

BREAKING CHANGE: reservation table schema changed, migration required

# ✅ Documentation
docs(readme): [#101] update setup instructions for monorepo

# ✅ Chore
chore(deps): [#202] update prisma to v5.0.0

# ✅ Multiple scopes
feat(frontend,api): [#345] implement real-time reservation updates

Workflow do Dia a Dia

1. Iniciar Nova Feature

# Atualizar main local
git checkout main
git pull origin main

# Criar branch de feature
git checkout -b feature/123-add-coupon-system

# Verificar se está na branch correta
git branch

2. Desenvolvimento

# Fazer mudanças e commits incrementais
git add .
git commit -m "feat(api): [#123] add coupon model and validation"

git add .
git commit -m "feat(api): [#123] implement coupon generation logic"

git add .  
git commit -m "test(api): [#123] add coupon generation tests"

3. Preparar para Review

# Rebase com main para histórico limpo
git checkout main
git pull origin main
git checkout feature/123-add-coupon-system
git rebase main

# Squash commits relacionados (se necessário)
git rebase -i HEAD~3  # Interativo para últimos 3 commits

# Push da branch
git push origin feature/123-add-coupon-system

4. Pull Request

Template de PR

## Descrição
Implementa sistema de geração de cupons com validação de dados e integração com o banco.

## Issue
Closes #123

## Testes
- [x] Unit tests para geração de cupom
- [x] Integration tests com banco
- [x] E2E test do fluxo completo

## Screenshots
[Se aplicável, adicionar screenshots da UI]

## Checklist
- [x] Código segue padrões ESLint
- [x] Testes passando
- [x] Documentação atualizada
- [x] Migration scripts incluídas (se aplicável)

Configuração de Branch Protection

# .github/branch-protection.yml
main:
  protection:
    required_status_checks:
      strict: true
      contexts:
        - "ci/tests"
        - "ci/lint"
        - "ci/type-check"
    enforce_admins: true
    required_pull_request_reviews:
      required_approving_review_count: 1
      dismiss_stale_reviews: true
      require_code_owner_reviews: true
    restrictions:
      users: []
      teams: ["core-team"]

Versionamento e Tags

Semantic Versioning (SemVer)

Formato: v[MAJOR].[MINOR].[PATCH][-prerelease]

Tipo	Quando usar	Exemplo
MAJOR	Breaking changes	v1.0.0 → v2.0.0
MINOR	Nova funcionalidade (backward compatible)	v1.0.0 → v1.1.0
PATCH	Bug fixes (backward compatible)	v1.0.0 → v1.0.1
Prerelease	Versões de teste	v1.1.0-beta.1

Automação via Conventional Commits

# Instalar ferramentas
npm install -g standard-version

# Gerar versão automaticamente baseada nos commits
standard-version

# Ou manualmente
git tag v1.2.0
git push origin v1.2.0

Changelog Automático

## [1.2.0](v1.1.0...v1.2.0) (2024-07-02)

### Features
* **api**: add coupon generation endpoint ([abc1234](commit-link))
* **frontend**: implement reservation form ([def5678](commit-link))

### Bug Fixes  
* **auth**: resolve JWT expiration handling ([ghi9012](commit-link))

### BREAKING CHANGES
* **database**: reservation schema migration required

Ferramentas e Automação

Git Hooks (Husky)

package.json

{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged",
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS",
      "pre-push": "npm run test"
    }
  },
  "lint-staged": {
    "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.md": ["prettier --write"]
  }
}

Commitlint Configuration

commitlint.config.js

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', [
      'feat', 'fix', 'docs', 'style', 'refactor', 
      'test', 'chore', 'perf', 'ci'
    ]],
    'subject-case': [2, 'always', 'lower-case'],
    'subject-max-length': [2, 'always', 72],
    'body-max-line-length': [2, 'always', 100]
  }
};

GitHub Actions Workflow

.github/workflows/pr-checks.yml

name: PR Checks
on:
  pull_request:
    branches: [main, develop]

jobs:
  lint-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      
      - name: Install dependencies
        run: npm ci
        
      - name: Lint code
        run: npm run lint
        
      - name: Type check
        run: npm run type-check
        
      - name: Run tests
        run: npm run test:coverage
        
      - name: Check commit format
        run: npx commitlint --from ${{ github.event.pull_request.base.sha }}

Métricas e Qualidade

Code Review Metrics

Métrica	Target	Ferramenta
Review time	< 24h	GitHub insights
PR size	< 500 lines changed	Danger.js
Test coverage	> 80%	Codecov
Commit message compliance	100%	Commitlint

Branch Hygiene

# Limpar branches locais já mergeadas
git branch --merged | grep -v "main\|develop" | xargs -n 1 git branch -d

# Limpar branches remotas
git remote prune origin

# Ver branches órfãs
git for-each-ref --format='%(refname:short) %(committerdate)' refs/heads | sort -k2

Troubleshooting

Problemas Comuns

Commit rejeitado por formato

# Erro: commit não segue Conventional Commits
# Solução: Alterar mensagem do último commit
git commit --amend -m "feat(api): [#123] add new endpoint"

Conflitos durante rebase

# Resolver conflitos manualmente, então:
git add .
git rebase --continue

# Se ficar muito complexo, abortar e fazer merge
git rebase --abort
git merge main

PR muito grande

# Dividir em commits menores
git rebase -i HEAD~5  # Squash ou split commits

# Ou criar PR incremental
git checkout -b feature/123-add-coupon-system-part-1
# Cherry-pick commits específicos
git cherry-pick abc1234 def5678

Checklist de Qualidade

Antes de Abrir PR

• Branch atualizada com main/develop
• Commits seguem Conventional Commits
• Testes passando localmente
• ESLint sem errors
• TypeScript sem errors
• Documentação atualizada se necessário

Durante Code Review

• Código readable e bem estruturado
• Lógica de negócio testada
• Error handling adequado
• Performance não degradada
• Segurança verificada
• Acessibilidade considerada (frontend)

---

Git workflow que promove qualidade, colaboração e entrega contínua