Este diretório contém arquivos de configuração e instruções para auxiliar no desenvolvimento e revisão de código do BrasilAPI.

Propósito: Instruções gerais para desenvolvimento assistido por IA

Uso:

• Referenciado automaticamente pelo GitHub Copilot durante desenvolvimento
• Guia para desenvolvedores entenderem padrões do projeto
• Define princípios fundamentais: compatibilidade, documentação, custos, qualidade

Conteúdo:

• Visão geral e missão do projeto
• Arquitetura e padrões de código
• Workflow para criar endpoints
• Exemplos de código e testes
• FAQ e comandos úteis

Propósito: Instruções específicas para revisão automática de PRs pelo GitHub Copilot

Uso:

• Treina o Copilot para revisar PRs seguindo nossos padrões
• Define critérios objetivos de aprovação/rejeição
• Automatiza parte do processo de code review

Conteúdo:

• Regras não-negociáveis (breaking changes, documentação, testes, segurança)
• Checklist obrigatória de revisão em 7 categorias
• Templates de feedback específico para cada tipo de problema
• Priorização: crítico vs importante vs sugestão
• Casos especiais (doc-only, dependabot, refatoração)

Como funciona:

1. Desenvolvedor abre PR
2. GitHub Copilot lê este arquivo
3. Copilot analisa mudanças seguindo checklist
4. Copilot comenta problemas encontrados com soluções específicas
5. Copilot sugere aprovação ou solicita mudanças

Propósito: Guia completo para revisores humanos

Uso:

• Consulta durante revisão manual de PRs
• Treinamento de novos revisores
• Referência para critérios de qualidade

Conteúdo:

• Checklist detalhada de revisão
• Como verificar compatibilidade de API
• Como validar documentação e testes
• Como avaliar performance e custos
• Como identificar vulnerabilidades
• Como dar feedback efetivo
• Red flags para rejeição imediata

Propósito: Template automático para todos os PRs

Uso:

• Aplicado automaticamente ao abrir novo PR
• Guia contribuidor no checklist antes de submeter
• Garante que informações essenciais sejam fornecidas

Conteúdo:

• Checklists de compatibilidade, documentação, testes, código
• Seção para descrever como testar
• Instruções para revisores
• Lembretes sobre impacto em produção

graph TD
    A[Desenvolvedor inicia mudança] --> B[Consulta copilot-instructions.md]
    B --> C[Implementa seguindo padrões]
    C --> D[Executa testes localmente]
    D --> E[Abre PR usando template]
    E --> F{Copilot Review Automático}
    F -->|Problemas| G[Desenvolvedor corrige]
    G --> F
    F -->|OK| H{Revisão Humana}
    H -->|Segue CODE_REVIEW_GUIDELINES| I[Aprovação]
    H -->|Problemas| J[Feedback detalhado]
    J --> G
    I --> K[Merge]

• ✅ Uso 100% automático
• Aplicado automaticamente quando qualquer pessoa abre um PR
• Não requer nenhuma configuração
• Funciona imediatamente após o merge

• ✅ Uso automático pelo GitHub Copilot
• GitHub Copilot no VS Code/IDE detecta e usa automaticamente
• Aplicado durante desenvolvimento quando Copilot está ativo
• Não requer configuração adicional no repositório
• Requisito: Desenvolvedor precisa ter GitHub Copilot instalado no IDE

• ⚙️ Uso via comando ou configuração
• Opção A - Uso manual por mantenedores: Comente no PR:

  @copilot review
  

  Ou mencione o arquivo específico:

  @copilot review following .github/copilot-review-instructions.md
  

• Opção B - Configuração automática (se disponível no plano):
  • GitHub Copilot Enterprise pode ter configuração para revisão automática
  • Verificar em Settings → Copilot do repositório
• Uso alternativo: Mantenedores podem usar como checklist manual

• 📖 Documento de referência - uso manual
• Revisores humanos consultam durante review
• Não é usado automaticamente por ferramentas
• Serve como guia e treinamento

• 📖 Documentação - uso manual
• Explicação sobre todos os outros arquivos
• Consultado quando necessário

1. Template de PR: Já funciona! Próximo PR terá o template automaticamente
2. Instruções de desenvolvimento: Desenvolvedores com Copilot já recebem as instruções automaticamente

Mantenedores devem, em cada PR importante:

# Comentar no PR para pedir revisão do Copilot
@copilot review

Isso fará o Copilot analisar o PR seguindo as regras em copilot-review-instructions.md

Revisores humanos devem consultar CODE_REVIEW_GUIDELINES.md como guia detalhado

Se sua organização tem GitHub Copilot Enterprise, você pode:

1. Ir em Settings → Copilot (no nível da organização ou repositório)
2. Procurar por opções de "Code Review" ou "PR Review"
3. Configurar revisão automática para todos os PRs
4. O Copilot usará copilot-review-instructions.md automaticamente

Nota: Esta funcionalidade pode não estar disponível em todos os planos. Consulte a documentação do GitHub Copilot para detalhes.

copilot-instructions.md:

• Novos padrões de código são adotados
• Mudanças em arquitetura
• Novos comandos ou ferramentas
• Lições aprendidas de erros comuns

copilot-review-instructions.md:

• Novos tipos de problemas frequentes em PRs
• Mudanças em critérios de aprovação
• Novos checks automatizados necessários
• Feedback que deve ser padronizado

CODE_REVIEW_GUIDELINES.md:

• Processos de revisão evoluem
• Novos requisitos de qualidade
• Melhores práticas são descobertas

PULL_REQUEST_TEMPLATE.md:

• Informações faltando frequentemente em PRs
• Novos checks necessários antes do merge

1. Abra PR com mudanças nas instruções
2. Explique motivo da mudança
3. Se possível, referencie PRs que motivaram a mudança
4. Peça feedback de outros mantenedores
5. Merge após aprovação

Todos esses arquivos refletem os princípios fundamentais do BrasilAPI:

1. 🔒 Compatibilidade é sagrada: Nunca quebre aplicações existentes
2. 📝 Documentação é obrigatória: Código sem doc não existe
3. 💰 Custos devem ser zero: Projeto deve ser sustentável sem financiamento
4. 🔐 Segurança em primeiro lugar: Proteção de dados e validação sempre
5. ✅ Qualidade é mandatória: Testes, linting, padrões são obrigatórios
6. 🌍 Open-source e comunidade: Decisões transparentes e colaborativas

• Para dúvidas sobre desenvolvimento: Ver copilot-instructions.md
• Para dúvidas sobre revisão: Ver CODE_REVIEW_GUIDELINES.md
• Para dúvidas sobre contribuição: Ver /CONTRIBUTING.md
• Para issues: github.com/BrasilAPI/BrasilAPI/issues

Mantido pela comunidade BrasilAPI 🇧🇷