9 min leitura • Guide 614 of 877
Boas Práticas de Controle de Versão
Controle de versão é a fundação do desenvolvimento colaborativo—permite que equipes trabalhem em código simultaneamente, rastreiem mudanças e coordenem releases. O GitScrum integra diretamente com GitHub e GitLab para conectar commits, branches e pull requests a tarefas, criando rastreabilidade completa da ideia ao deploy. A estratégia de branching e práticas de commit certas fazem a diferença entre colaboração suave e caos de conflitos de merge.
Estratégias de Branching
| Estratégia | Complexidade | Melhor Para |
|---|---|---|
| Trunk-based | Baixa | Deploy contínuo |
| GitHub Flow | Baixa | Releases regulares |
| GitFlow | Alta | Releases agendados |
| Forking | Média | Open source |
Workflows de Branching
COMPARAÇÃO DE ESTRATÉGIAS DE BRANCHING
TRUNK-BASED DEVELOPMENT:
┌─────────────────────────────────────────────────┐
│ main ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ ╲ ╱ ╲ ╱ ╲ ╱ │
│ ┊ ┊ ┊ │
│ (branches pequenos e curtos) │
│ │
│ Características: │
│ ├── Commits pequenos e frequentes na main │
│ ├── Feature flags para trabalho incompleto │
│ ├── Branches vivem < 1 dia │
│ └── CI contínua essencial │
│ │
│ Melhor para: Times com deploy contínuo │
└─────────────────────────────────────────────────┘
GITHUB FLOW:
┌─────────────────────────────────────────────────┐
│ main ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ ╲ ╱ ╲ ╱ │
│ ╲────────╱ ╲────────╱ │
│ feature-x feature-y │
│ │
│ Workflow: │
│ 1. Branch a partir da main │
│ 2. Commita no branch │
│ 3. Abre PR quando pronto │
│ 4. Review e discussão │
│ 5. Merge na main │
│ 6. Deploy a partir da main │
│ │
│ Melhor para: Ciclos de release simples │
└─────────────────────────────────────────────────┘
GITFLOW:
┌─────────────────────────────────────────────────┐
│ main ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ ╲ ╱ │
│ develop ─────────●─────────●───────── │
│ ╱ ╲ ╱ │
│ feature-a feature-b │
│ ╲ │
│ release/1.0 │
│ ╲ │
│ hotfix ─────────────────────●──── │
│ │
│ Branches: │
│ ├── main: Código de produção │
│ ├── develop: Branch de integração │
│ ├── feature/*: Novas features │
│ ├── release/*: Preparação de release │
│ └── hotfix/*: Correções de produção │
│ │
│ Melhor para: Releases agendados, versionados │
└─────────────────────────────────────────────────┘
Nomenclatura de Branches
CONVENÇÕES DE NOMENCLATURA DE BRANCHES
ESTRUTURA:
┌─────────────────────────────────────────────────┐
│ tipo/descricao │
│ tipo/issue-descricao │
│ │
│ Exemplos: │
│ ├── feature/autenticacao-usuario │
│ ├── feature/GS-123-exportar-csv │
│ ├── fix/erro-timeout-login │
│ ├── fix/GS-456-validacao-faltando │
│ ├── refactor/simplificar-fluxo-pagamento │
│ ├── docs/documentacao-api │
│ └── chore/atualizar-dependencias │
└─────────────────────────────────────────────────┘
TIPOS:
┌─────────────────────────────────────────────────┐
│ feature/ - Novas features │
│ fix/ - Correções de bugs │
│ hotfix/ - Correções urgentes de produção │
│ refactor/ - Refatoração de código │
│ docs/ - Documentação │
│ chore/ - Tarefas de manutenção │
│ test/ - Adição de testes │
│ release/ - Preparação de release │
└─────────────────────────────────────────────────┘
REGRAS:
┌─────────────────────────────────────────────────┐
│ ✓ Apenas minúsculas │
│ ✓ Hífens para separar palavras │
│ ✓ Incluir número do ticket se aplicável │
│ ✓ Descritivo mas conciso │
│ ✗ Sem espaços │
│ ✗ Sem caracteres especiais │
│ ✗ Sem nomes muito longos │
└─────────────────────────────────────────────────┘
Práticas de Commit
Mensagens de Commit
COMMITS CONVENCIONAIS
═════════════════════
FORMATO:
─────────────────────────────────────
tipo(escopo): assunto
corpo (opcional)
footer (opcional)
TIPOS COMUNS:
─────────────────────────────────────
feat: Nova feature
fix: Correção de bug
docs: Apenas documentação
style: Formatação (sem mudança de código)
refactor: Refatoração de código
test: Adição de testes
chore: Manutenção, build, etc.
perf: Melhoria de performance
EXEMPLOS:
─────────────────────────────────────
feat(auth): add OAuth2 login support
fix(api): resolve timeout on large exports
Increased timeout from 30s to 60s for export
operations that process >1000 records.
Fixes GS-456
docs(readme): update installation instructions
refactor(payment): extract validation logic
REGRAS PARA ASSUNTO:
─────────────────────────────────────
✓ Imperativo ("add" não "added" ou "adds")
✓ Primeira letra minúscula
✓ Sem ponto final
✓ Máximo 72 caracteres
✓ Descreve O QUE, não COMO
Anatomia de Bons Commits
COMMITS ATÔMICOS
════════════════
UM COMMIT = UMA MUDANÇA LÓGICA
─────────────────────────────────────
Bom:
├── feat(user): add email validation
├── fix(cart): prevent duplicate items
├── refactor(api): extract response handler
└── Cada commit faz uma coisa
Ruim:
├── "various fixes and updates"
├── "WIP"
├── "changes"
└── Commits que fazem várias coisas
TAMANHO IDEAL:
─────────────────────────────────────
├── Pequeno o suficiente para entender
├── Grande o suficiente para ser significativo
├── Pode ser revertido independentemente
├── Não quebra o build
└── Passa nos testes
COMMITS RELACIONADOS:
─────────────────────────────────────
Feature completa pode ter:
├── Commit 1: Adiciona modelo de dados
├── Commit 2: Implementa lógica de negócio
├── Commit 3: Adiciona testes
├── Commit 4: Adiciona endpoint API
├── Commit 5: Atualiza documentação
└── Cada um completo e funcional
Pull Requests
Boas Práticas de PR
PULL REQUESTS EFETIVOS
══════════════════════
TAMANHO:
─────────────────────────────────────
Ideal: < 400 linhas de código
Máximo: 1000 linhas (exceto gerado)
Muito grande: Difícil de revisar bem
Se PR é muito grande:
├── Quebrar em PRs menores
├── Stacked PRs se dependente
├── Feature flags para parcial
└── Refatoração separada de feature
TÍTULO E DESCRIÇÃO:
─────────────────────────────────────
Título:
[GS-123] Add user export functionality
Descrição:
## O que esse PR faz
Adiciona funcionalidade para exportar
dados de usuário em CSV.
## Por que é necessário
Requisito do cliente para compliance LGPD.
## Como testar
1. Login como admin
2. Vá para Users > Export
3. Clique "Export CSV"
4. Verifique arquivo baixado
## Screenshots
[Se houver mudanças de UI]
## Checklist
- [x] Testes adicionados
- [x] Documentação atualizada
- [x] Sem console.logs
- [x] Migração incluída
VINCULANDO A TAREFAS:
─────────────────────────────────────
├── Mencionar ID no título: [GS-123]
├── Usar "Closes GS-123" na descrição
├── Link automático no GitScrum
└── Status atualiza automaticamente
Code Review
PROCESSO DE CODE REVIEW
═══════════════════════
COMO REVIEWER:
─────────────────────────────────────
Verificar:
├── Lógica correta?
├── Edge cases cobertos?
├── Testes adequados?
├── Performance ok?
├── Segurança considerada?
├── Código legível?
└── Padrões seguidos?
Feedback construtivo:
├── Específico e acionável
├── Explique o porquê
├── Sugira alternativas
├── Reconheça o que está bom
└── Diferencie must-fix de nit
Exemplo bom:
"Sugiro extrair essa lógica para um
método separado para facilitar testes.
Algo como `validateUserInput(data)`"
Exemplo ruim:
"Esse código é confuso"
COMO AUTOR:
─────────────────────────────────────
├── Auto-review antes de submeter
├── Responder a todos os comentários
├── Agradecer feedback
├── Explicar decisões se necessário
├── Fazer mudanças solicitadas
└── Re-request review após mudanças
TEMPO DE RESPOSTA:
─────────────────────────────────────
SLA recomendado:
├── Primeira olhada: < 4 horas
├── Review completo: < 24 horas
├── Não deixar PRs mofando
└── Priorizar unblock do colega
Integração com GitScrum
Conectando Commits a Tarefas
RASTREABILIDADE COMPLETA
════════════════════════
CONVENÇÃO DE COMMIT:
─────────────────────────────────────
feat(auth): add password reset GS-123
GitScrum automaticamente:
├── Linka commit à tarefa GS-123
├── Mostra commit no histórico da tarefa
├── Atualiza atividade recente
└── Permite navegar código↔tarefa
BRANCH LINKADO:
─────────────────────────────────────
Branch: feature/GS-123-password-reset
GitScrum automaticamente:
├── Detecta ID no nome do branch
├── Linka branch à tarefa
├── Mostra status do branch
└── PR automático linkado
PR LINKADO:
─────────────────────────────────────
PR Title: [GS-123] Add password reset
ou PR Body: Closes GS-123
GitScrum automaticamente:
├── Linka PR à tarefa
├── Move tarefa para "In Review"
├── Quando merged → "Done"
└── Visibilidade para todo time
Automações
AUTOMAÇÕES GITSCRUM + GIT
═════════════════════════
PR OPENED → IN REVIEW:
─────────────────────────────────────
Trigger: PR aberto com task ID
Ação: Move tarefa para "In Review"
Benefício: Status sempre atualizado
PR MERGED → DONE:
─────────────────────────────────────
Trigger: PR mergeado na main
Ação: Move tarefa para "Done"
Benefício: Sem update manual
COMMIT → ATIVIDADE:
─────────────────────────────────────
Trigger: Commit com task ID
Ação: Registra atividade na tarefa
Benefício: Timeline completa
CONFIGURANDO:
─────────────────────────────────────
Settings → Integrations → GitHub/GitLab
├── Autorizar acesso
├── Selecionar repos
├── Configurar automações
├── Definir padrões de ID
└── Testar conexão
Boas Práticas Gerais
O Que Fazer e Não Fazer
BOAS PRÁTICAS DE VERSION CONTROL
════════════════════════════════
FAÇA:
─────────────────────────────────────
✓ Commits pequenos e frequentes
✓ Mensagens descritivas
✓ Branches curtos (< 1 semana)
✓ Pull antes de push
✓ Review antes de merge
✓ Testes passando antes de merge
✓ Main sempre deployável
NÃO FAÇA:
─────────────────────────────────────
✗ Commit de código que não compila
✗ Push direto na main
✗ Branches de longa duração
✗ Merge sem review
✗ Commit de secrets/senhas
✗ Commit de arquivos gerados
✗ Force push em branches compartilhados
CONFIGURAR .gitignore:
─────────────────────────────────────
Incluir:
├── node_modules/
├── .env
├── *.log
├── dist/
├── coverage/
├── .DS_Store
└── IDE configs pessoais
Resolução de Conflitos
GERENCIANDO CONFLITOS DE MERGE
══════════════════════════════
PREVENÇÃO:
─────────────────────────────────────
├── Branches curtos
├── Merge frequente de main
├── Comunicação sobre áreas de código
├── Code ownership claro
└── PRs pequenos
QUANDO ACONTECE:
─────────────────────────────────────
1. Não entre em pânico
2. Entenda ambas as mudanças
3. Fale com o outro dev se necessário
4. Resolva mantendo intenção de ambos
5. Teste após resolução
6. Review cuidadoso do merge
FERRAMENTAS:
─────────────────────────────────────
├── VS Code merge tool
├── git mergetool
├── GitHub conflict resolver
├── Pair resolving para complexos
└── Testes automatizados validam