Convenção para Pull Requests

Um PR ou Pull Request (em português, "Solicitação de Pull") é um termo utilizado em plataformas de controle de versão como GitHub, GitLab e Bitbucket. Ele é um processo pelo qual um desenvolvedor propõe que as mudanças que ele fez em uma branch (ramo) do repositório sejam mescladas (ou "mergeadas") na branch principal ou em outra branch específica.

1. Uso do Template de Pull Request

• Obrigatório: Todo Pull Request (PR) deve utilizar o template padrão definido pela equipe.
• Estrutura: O template deve ser preenchido completamente, incluindo as seções de descrição, tipo de mudança, como testar, checklist, issues relacionadas, screenshots (se aplicável) e comentários adicionais.

2. Nomeação da Pull Request

• Descrição Resumida: O nome da PR deve conter uma descrição resumida e clara do pacote ou funcionalidade que está sendo entregue.
• Padrões de Nomenclatura: Seguir convenções pré-definidas para nomes de PRs, facilitando a identificação e rastreamento das mudanças.

3. Conformidade com Gitflow

• Fluxo de Trabalho: Todas as PRs devem seguir o processo do Gitflow, incluindo a criação de branches específicas (feature, release, hotfix) conforme necessário.
• Nomenclatura de Branches: As branches devem ser nomeadas seguindo as convenções estabelecidas para manter a consistência e clareza.

4. Padrões de Código e Estilo

• Conformidade com Padrões: Todo código submetido deve seguir os padrões de codificação estabelecidos pela equipe ou organização.
• Ferramentas de Linting: Utilizar ferramentas de linting automáticas para garantir a consistência e qualidade do código.
• Formatação Automática: Implementar formatação automática de código usando ferramentas adequadas ao stack tecnológico utilizado.

5. Testes Automatizados

• Cobertura de Testes: Garantir que novas funcionalidades estejam acompanhadas de testes automatizados adequados (unidade, integração, end-to-end).
• Requisitos de Cobertura: Manter ou melhorar o percentual de cobertura de testes com cada PR submetida.
• Execução Automática de Testes: Configurar a pipeline para executar testes automaticamente em cada PR submetida.

6. Atualização de Documentação

• Documentação Necessária: Qualquer mudança que afete a funcionalidade ou uso do sistema deve ser refletida na documentação correspondente.
• Manuais e READMEs: Atualizar manuais de usuário, arquivos README e demais documentos relevantes com as alterações realizadas.
• Comentários no Código: Incluir comentários claros e concisos no código para facilitar o entendimento e manutenção futura.

7. Evidência de Uso

• Evidência Obrigatória: Cada PR deve incluir evidências de que a mudança foi testada e está funcionando corretamente, podendo ser na forma de imagens, vídeos ou logs relevantes.

8. Aprovação de Pull Request

• Mínimo de Aprovações: Cada PR deve ter, no mínimo, duas aprovações antes de ser mesclada.
• Atribuição de Revisores: Revisores serão designados conforme a área de expertise e disponibilidade, seguindo um sistema de rodízio para distribuir a carga de trabalho e compartilhar conhecimento.
• Tempo de Resposta: Revisores devem fornecer feedback sobre as PRs atribuídas dentro de um prazo de 2 dias úteis.

9. Rejeição de Pull Requests

• Nomenclatura e Padrões: Qualquer PR cujo nome da branch, mensagens de commit ou nome da PR não sigam as convenções será automaticamente rejeitada.
• Motivo da Rejeição: Ao negar uma PR, é obrigatório fornecer uma justificativa clara e específica, indicando as correções necessárias.
• Quem Pode Rejeitar: Qualquer membro da equipe tem o direito de negar uma PR se ela não estiver em conformidade com as regras estabelecidas.

10. Tamanho e Escopo da PR

• PRs Pequenas e Focadas: PRs devem ser menores e com escopo bem definido para facilitar a revisão e integração.
• Divisão de Funcionalidades: Grandes funcionalidades devem ser divididas em múltiplas PRs menores e incrementais quando possível.

11. Configuração de Merge

• Exclusão de Branch: Todas as PRs devem ter a opção de excluir a branch ativada ao realizar o merge.
• Estratégia de Merge: O merge deve ser realizado utilizando a estratégia git merge --no-ff para manter o histórico de commits claro e organizado.

12. Resolução de Conflitos

• Resolução Obrigatória: Todos os conflitos devem ser resolvidos antes que uma PR possa ser mesclada.
• Prazo para Resolução: Se o conflito não for resolvido ou se houver falha no build dentro de um prazo de 2 dias, a PR poderá ser negada ou retornada para correção.

13. Feedback e Melhoria Contínua

Ao revisar um Pull Request, é importante fornecer feedback claro e construtivo para ajudar o autor a entender as mudanças necessárias e os ajustes que podem melhorar o código. Para facilitar esse processo, os comentários devem ser categorizados utilizando labels específicas. As labels indicam a gravidade ou importância do comentário, orientando o autor sobre como priorizar as mudanças sugeridas.

Categorias de Comentários

1. NICE TO HAVE

   • Descrição: Sugestões que não são obrigatórias, mas que podem melhorar a qualidade do código ou a experiência do usuário. Essas mudanças são opcionais e o autor pode optar por implementá-las ou não.
   • Exemplo: [NICE TO HAVE] Seria interessante adicionar uma documentação extra para esta função, mas o código está claro sem ela.

2. REQUEST

   • Descrição: Ajustes ou correções necessárias para que o código seja aceito. Esses comentários indicam algo que deve ser resolvido antes de o PR ser aprovado.
   • Exemplo: [REQUEST] Precisa refatorar esta função para melhorar a legibilidade e evitar duplicação de código.

3. BUG

   • Descrição: Indica um erro ou comportamento incorreto no código que deve ser corrigido. Comentários com esta label são críticos e devem ser priorizados.
   • Exemplo: [BUG] Há um bug aqui que pode causar uma exceção se a variável for nula.

4. IMPROVEMENT

   • Descrição: Sugestões de melhorias que, embora não sejam essenciais, irão melhorar o desempenho, a manutenção ou a eficiência do código.
   • Exemplo: [IMPROVEMENT] A função poderia ser otimizada usando um algoritmo de busca binária em vez de uma busca linear.

5. QUESTION

   • Descrição: Usado para levantar dúvidas ou pedir esclarecimentos sobre o código. Isso pode incluir perguntas sobre decisões de design ou sobre a lógica implementada.
   • Exemplo: [QUESTION] Por que você optou por usar esta biblioteca em vez de outra mais comum?

6. BLOCKER

   • Descrição: Questões críticas que impedem o merge do PR até que sejam resolvidas. Esse tipo de comentário geralmente está associado a problemas graves no código.
   • Exemplo: [BLOCKER] Este PR não pode ser aprovado até que o problema de segurança com a autenticação seja resolvido.