commit-workflow

name	commit-workflow
description	Fluxo completo de Git: branches, commits, pull requests e code review

Commit Workflow

Quando Usar

Ativar quando:

• Código está pronto para commit
• Review foi aprovado
• Testes passaram

Conventional Commits

Formato

<type>(<scope>): <description>

[body opcional]

[footer opcional]

Types

Type	Uso
feat	Nova funcionalidade
fix	Correção de bug
docs	Documentação
style	Formatação (não afeta código)
refactor	Refatoração
test	Testes
chore	Manutenção
perf	Performance
ci	CI/CD

Scope

Área afetada: auth, api, ui, db, etc.

Exemplos

feat(auth): add JWT refresh token endpoint
fix(api): handle null response in user service
docs(readme): update installation instructions
refactor(utils): extract date formatting to helper
test(auth): add unit tests for login flow
chore(deps): update dependencies to latest

Workflow Obrigatório

1. Verificar Status

git status
git diff --stat

2. Mostrar Alterações

git diff

3. Sugerir Mensagem

Baseado nas alterações, sugerir mensagem seguindo conventional commits.

4. PEDIR CONFIRMAÇÃO

Commit sugerido:
feat(auth): implement password reset

Arquivos: 3 modificados, 45+, 12-

**Posso fazer o commit?** [AGUARDAR RESPOSTA]

5. Executar (só com permissão)

git add -A
git commit -m "mensagem"

6. Perguntar sobre Push

Commit feito. **Quer fazer push?** [AGUARDAR RESPOSTA]

Regras CRÍTICAS

NUNCA sem permissão:

• git commit
• git push
• git reset --hard
• git rebase
• git merge

SEMPRE fazer:

• Mostrar diff antes
• Pedir confirmação explícita
• Usar conventional commits
• NUNCA adicionar co-author de IA

CHANGELOG Obrigatório

ANTES de commitar, SEMPRE atualizar o CHANGELOG:

1. Verificar se CHANGELOG.md existe na raiz do projeto
2. Se não existir, criar seguindo o template em skills/workflow/changelog/SKILL.md
3. Adicionar todas as mudanças em [Unreleased]
4. Categorizar corretamente: Added, Changed, Deprecated, Removed, Fixed, Security
5. NUNCA modificar versões já lançadas

Ver skills/workflow/changelog/SKILL.md para detalhes completos.

---

---

Workflow de Branches

Feature Branches Obrigatório

# Sempre usar feature branches
git checkout -b feature/nome-da-feature
git checkout -b fix/nome-do-bug
git checkout -b refactor/nome-do-refactor

Estrutura de Branches

main                    # produção (protegida)
├── develop            # desenvolvimento (opcional)
├── feature/xxx        # novas features
├── fix/xxx            # correções de bugs
├── refactor/xxx       # refatorações
└── hotfix/xxx         # correções urgentes em produção

Git Flow Simplificado

Princípios:

• main sempre estável e deployável
• Features desenvolvidas em branches separadas
• Merge apenas via pull request
• Code review obrigatório antes de merge
• Hotfixes: podem ser commitados direto em main (correções urgentes em produção)

Fluxo:

1. Criar branch a partir de main
2. Desenvolver feature
3. Commitar frequentemente com mensagens descritivas
4. Criar pull request
5. Code review
6. Merge após aprovação
7. Deletar branch após merge

Hotfixes (exceção):

• Correções urgentes em produção
• Podem ser commitados direto em main
• Usar tipo fix: ou hotfix: no commit
• Exemplo: fix: corrigir erro crítico em produção

---

Pull Requests

Antes de Criar PR

• Código testado localmente
• Todos os testes passando
• Sem conflitos com main
• Código revisado (self-review)
• Documentação atualizada se necessário
• CHANGELOG.md atualizado

Descrição do PR

## Descrição
Breve descrição do que foi feito.

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

## Checklist
- [ ] Testes adicionados/atualizados
- [ ] Documentação atualizada
- [ ] Código segue padrões do projeto
- [ ] Sem breaking changes (ou documentados)
- [ ] CHANGELOG.md atualizado

---

Code Review

Antes de Aprovar

• Código segue padrões do projeto
• Testes adequados
• Sem código comentado desnecessário
• Sem secrets hardcoded
• Performance considerada
• Segurança considerada
• CHANGELOG.md atualizado

Feedback

• Ser construtivo e educacional
• Explicar o porquê das sugestões
• Sugerir alternativas quando possível
• Reconhecer boas práticas

---

Tags e Releases

Semantic Versioning

v<major>.<minor>.<patch>

• major: breaking changes
• minor: novas features (backward compatible)
• patch: bug fixes

Criar Tag

git tag -a v1.2.0 -m "Release 1.2.0: Adicionar autenticação JWT"
git push origin v1.2.0

Ver: skills/workflow/changelog/SKILL.md para processo completo de releases.

---

Regras Gerais

Nunca Fazer

• ❌ Force push para main
• ❌ Commits diretos em main (sempre via PR, exceto hotfixes)
• ❌ Commits sem mensagem descritiva
• ❌ Commits com código quebrado
• ❌ Commits com secrets
• ❌ Commits sem atualizar CHANGELOG.md

Sempre Fazer

• ✅ Usar feature branches
• ✅ Commits frequentes e descritivos
• ✅ Revisar código antes de commit
• ✅ Rodar testes antes de commit
• ✅ Atualizar documentação quando necessário
• ✅ Atualizar CHANGELOG.md antes de commitar

---

Boas Práticas Adicionais

Commits Frequentes

Fazer commits pequenos e frequentes:

• Cada commit deve representar uma mudança lógica
• Commits frequentes facilitam rollback
• Commits pequenos facilitam code review

Antes de Commit

• Código testado localmente
• Todos os testes passando
• Código formatado (black, prettier, etc.)
• Sem código comentado desnecessário
• Sem console.log/debugger
• Sem secrets hardcoded
• CHANGELOG.md atualizado

Organização de Commits

Um commit = uma responsabilidade:

# ✅ Correto - commits separados
git commit -m "feat: adicionar validação de email"
git commit -m "refactor: mover lógica para controller"
git commit -m "test: adicionar testes para validação"

# ❌ Errado - tudo em um commit
git commit -m "feat: adicionar validação e refatorar controller e testes"

---

Resolução de Problemas

Conflitos de Merge

# Atualizar branch local
git pull origin main

# Resolver conflitos manualmente
# Editar arquivos marcados com conflito

# Adicionar arquivos resolvidos
git add .

# Continuar merge
git commit

---

Checklist

• CHANGELOG.md atualizado com todas as mudanças em [Unreleased]
• Review aprovado
• Testes passando
• Diff mostrado ao usuário
• Mensagem segue conventional commits
• Confirmação obtida
• Commit executado
• Push perguntado (se aplicável)