Pull Request Standards

Este documento define o padrão Arkorizon para Pull Requests. O objetivo é garantir revisão clara, rastreabilidade, segurança e qualidade antes de qualquer mudança chegar na main.

Princípios

• Todo trabalho deve passar por Pull Request.
• A main deve estar sempre estável, testada e deployável.
• O PR deve explicar contexto, motivação, impacto esperado e riscos.
• O PR deve ser pequeno o suficiente para revisão humana eficiente.
• CI deve validar build, testes, lint e documentação quando aplicável.
• Revisores devem avaliar comportamento, arquitetura, segurança e manutenção.

Título do PR

O título do PR deve seguir o padrão de Conventional Commits.

<type>(<scope>): <summary>

Exemplos:

feat(auth): add refresh token rotation
fix(sync): handle offline startup
docs(standards): expand repository standards
ci(pages): add MkDocs deployment workflow

Descrição do PR

Todo PR deve responder:

• O que foi alterado?
• Por que foi alterado?
• Qual problema, oportunidade ou necessidade motivou a mudança?
• Qual impacto positivo a mudança deve gerar?
• Existe risco técnico, operacional, de segurança, dados ou compatibilidade?
• Há alguma informação adicional que ajude a revisão?

Template recomendado:

## Summary
- Describe what changed.
- Mention the affected area.

## Motivation
- Explain why this change is needed.
- If this is a fix, describe what problem is corrected.
- If this is an improvement, describe the expected positive impact.

## Risk
- Low / Medium / High
- Explain the main risk, if any.

## Additional Context
- Add screenshots, links, rollout notes, migration notes or follow-ups when needed.

Não inclua checklist manual de validação no template padrão. A validação obrigatória deve aparecer na esteira de CI/CD e nas regras do repositório. Se uma validação manual for relevante, descreva em Additional Context.

Tamanho do PR

Prefira PRs pequenos e coesos.

Tamanho	Orientação
Pequeno	Ideal. Uma mudança clara, fácil de revisar.
Médio	Aceitável quando a feature exige consistência entre arquivos.
Grande	Deve ser exceção. Explique por que não pode ser dividido.

Um PR grande pode ser aceito quando separar a mudança deixaria o sistema inconsistente, quebrado ou impossível de validar.

Regras obrigatórias

• Não fazer merge na main sem Pull Request, exceto bypass administrativo justificado.
• Respeitar as rulesets globais da organização.
• Resolver comentários antes do merge.
• Atualizar documentação quando o comportamento mudar.
• Não misturar mudanças sem relação.
• Apagar branch após merge quando possível.

Regras de branch, commit e proteção da main ficam em Organization Rulesets.

Revisão obrigatória

A revisão deve avaliar:

• correção funcional;
• clareza do código;
• aderência à arquitetura;
• segurança;
• performance;
• testes;
• documentação;
• observabilidade quando aplicável;
• impacto operacional.

Checklist do autor

Antes de pedir review:

• O PR tem título semântico.
• A descrição explica contexto e impacto.
• O código compila.
• Testes relevantes foram executados.
• Documentação foi atualizada quando necessário.
• Não há secrets, tokens ou credenciais.
• Não há arquivos gerados desnecessários.
• O diff foi revisado pelo autor.

Checklist do revisor

Durante a revisão:

• A mudança resolve o problema correto.
• O escopo está claro.
• Não há acoplamento desnecessário.
• As regras de arquitetura foram respeitadas.
• Erros e exceções foram tratados.
• Testes cobrem o comportamento importante.
• Não há risco óbvio de segurança.
• Nomes estão consistentes com os padrões.
• O PR pode ser mantido no longo prazo.

Estratégia de merge

Estratégia	Quando usar
Squash merge	Padrão para features, fixes e docs. Mantém histórico limpo.
Merge commit	Releases ou PRs que precisam preservar commits individuais.
Rebase merge	Mudanças pequenas quando o time quiser histórico linear.

Padrão recomendado: Squash merge com título final seguindo Conventional Commits.

O formato de commit fica em Commit Semântico.

PRs de hotfix

Hotfix deve ser usado para correção urgente em produção.

O PR de hotfix deve conter:

• descrição do incidente;
• impacto;
• motivo da urgência;
• plano de rollback;
• referência a issue/incidente quando existir.

Regras para aprovação

• PR deve ter pelo menos uma aprovação quando o repositório exigir.
• Regras de aprovação devem ser definidas nas rulesets ou branch protection do repositório.
• Administradores da organização podem ter bypass para casos operacionais, incidentes ou manutenção crítica.
• Exceções administrativas devem ser usadas apenas quando necessário e com responsabilidade.
• A aprovação deve confirmar que a mudança é compreensível, revisável e alinhada ao objetivo descrito.

Regra final

Um PR deve ser revisável por outra pessoa sem reunião obrigatória.

Se o revisor precisa perguntar o objetivo básico da mudança, a descrição do PR está incompleta.