Introdução
Neste tutorial, você acompanhará uma única pull request pela análise do Code Quality, do primeiro comentário até a mesclagem. O que você aprenderá:
- Como ler os Code Quality comentários em sua solicitação de pull.
- Como usar o rótulo de gravidade de uma descoberta para decidir o que corrigir, o que ignorar e em que ordem.
- Como as escolhas que você faz em uma pull request moldam as pontuações do repositório, a lista de pendências e os limites da mesclagem.
Ao final, você terá resolvido cada resultado impeditivo na pull request de exemplo e mesclado com uma verificação Code Quality limpa, e entenderá por que tomou cada decisão.
Este é um tutorial guiado, portanto prioriza a compreensão em vez da velocidade. Para ver as etapas básicas de como confirmar uma correção automática ou descartar um resultado, consulte o guia complementar: Corrigindo descobertas de qualidade de código em uma solicitação de pull.
Antes de começar
- Code Quality está habilitado em um repositório para o qual você contribui. Consulte Habilitando o GitHub Code Quality.
- O repositório usa um idioma compatível com CodeQL para que resultados e pontuações baseados em regras sejam gerados. Para obter uma lista de idiomas com suporte, consulte Qualidade do Código do GitHub.
- Você tem uma pull request aberta para a ramificação padrão com pelo menos um resultado Code Quality para triagem. Se você não tiver uma solicitação de pull pronta, poderá seguir o exemplo abaixo.
Ao longo deste tutorial, usaremos um exemplo em execução: uma solicitação de pull que refatora algum código introduzirá vários problemas de qualidade de código no branch padrão se ele for mesclado como está. Um exame Code Quality foi realizado automaticamente na pull request e relatou diversos resultados como comentários.
Por que o pull request é o melhor lugar para corrigir um problema identificado
Todo problema que você não resolve na etapa do pull request se torna uma tarefa no backlog do repositório, e a dívida técnica geralmente é mais custosa de quitar depois do que corrigi-la agora. Neste momento, enquanto o pull request está aberto, o contexto e a intenção do código ainda estão frescos na sua mente, o que torna cada apontamento, e sua correção automática, mais fácil e rápido de avaliar, aplicar ou descartar com confiança.
Resolver os resultados no estágio de pull request significa que a equipe passa menos tempo fazendo o trabalho de triagem em vez do desenvolvimento de funcionalidades e evita a sobrecarga de pull requests extras apenas para reduzir a lista de pendências.
Etapa 1: Encontre os comentários na sua Code Quality pull request
Quando você abre uma solicitação de pull, Code Quality usa CodeQL para verificar suas alterações em um conjunto de regras e posta descobertas como comentários por github-code-quality[bot]. Cada comentário inclui um autofixo sugerido. Abra a guia Arquivos alterados da sua solicitação de pull para examinar as descobertas.
Em nosso exemplo, examinaremos três comentários de github-code-quality[bot]. Observe os rótulos de severidade em cada um. A etapa 2 explica o que eles significam.
Etapa 2: Ler o rótulo de severidade para decidir o que importa
Cada descoberta por meio de um rótulo de github-code-quality[bot] severidade – Erro, Aviso ou Observação. Localize o rótulo em um dos comentários e verifique-o nesta tabela.
| Severity | Definition |
|---|---|
| Error | Indica um problema de alta gravidade que provavelmente causará bugs, falhas ou principais riscos de manutenção. |
| Aviso | Indica um problema de gravidade moderada que pode afetar a qualidade ou a confiabilidade do código, mas não é imediatamente crítico. |
| Observação | Indica um problema de baixa gravidade, um pequeno aprimoramento ou uma recomendação. Essas descobertas são úteis para a integridade e a manutenção contínuas do código. |
A etiqueta está desempenhando duas funções ao mesmo tempo para você:
- Ele informa o que corrigir primeiro. A gravidade reflete o impacto esperado de uma regra no código típico. Em nosso exemplo, você começará com o Erro, depois o Aviso e trataria a Observação como um polimento opcional.
- Ele pode decidir se você pode mesclar. Um administrador de repositório ou proprietário da organização pode configurar Code Quality como uma porta de mesclagem. Por exemplo, se o limiar para mesclagem for "Aviso e acima", cada resultado de nível AvisoeErro deverá ser corrigido ou descartado antes que você possa mesclar (resultados de Nota não impediriam a mesclagem). Da mesma forma, um limite mais rigoroso pode exigir que você resolva todas as descobertas antes da mesclagem.
Para ver se há um bloqueio, role até a seção Verificações na parte inferior da pull request. Se suas alterações ficarem abaixo do limiar exigido, você verá um aviso de bloqueio de mesclagem: "A mesclagem está bloqueada: foram detectados problemas de qualidade do código."
Em nosso exemplo, a porta é definida como "Aviso e acima", logo, a faixa está presente: o Erro e o Aviso estão impedindo a mesclagem e a Observação não está. Isso mostra o que você precisa resolver antes que este pull request possa ser mesclado.
Se a faixa do bloco de mesclagem não especificar um nível de gravidade, você deverá limpar todos os resultados para mesclar a pull request.
Etapa 3: Resolver cada descoberta
Para cada descoberta, decida se ela se aplica ao seu código e, se isso acontecer, como corrigi-lo. Isso leva você a uma das três ações.
| Assessment | Ação recomendada | Notes |
|---|---|---|
| A descoberta é legítima e a correção sugerida parece correta | ||
| Aplicar a sugestão de correção automática | Clicar em Sugestão de Confirmação não consome AI creditse os autofixos não exigem uma Copilot licença. | |
| A descoberta é real, mas você deseja corrigir várias de uma vez ou a correção sugerida precisa ser adaptada | ||
Delegar para Copilot— mencione @copilot em um comentário para entregar o trabalho ao agente de nuvem. | ||
| Copilot reage a 👀, inicia uma nova sessão de agente e faz push das correções necessárias para a ramificação da pull request | Requer uma Copilot licença e consome AI credits. | |
| O resultado não se aplica, por exemplo, trata-se do código de teste, um padrão intencional ou um falso positivo. | Clique em Descartar resultado e forneça um motivo | Você poderá mesclar a pull request, mas o alerta aparecerá no backlog do repositório e em pull requests futuras. |
Aplique a prática à própria pull request seguindo a ordem de gravidade.
Em nosso exemplo:
- As ocorrências de nível Erro e Aviso são erros reais, e as correções automáticas sugeridas parecem razoáveis, por isso aplicamos as sugestões de correção automática. Os resultados são resolvidos e deixam de ser contabilizados na contagem de bloqueios.
- Um resultado no nível Observação sinaliza um padrão secundário em um auxiliar de teste adjacente. É intencional, logo, descartamos com um motivo como "Usado em testes".
- Há vários achados adicionais no nível de Nota. Em vez de percorrer cada sugestão de correção automática, uma por uma, comentamos: "
@copilot, corrija todos os problemas no nível Observação restantes". Acompanhamos o progresso de Copilot na guia Agentes do repositório e revisamos os commits enviados por ele para a pull request quando estão prontos.
Etapa 4: confirmar se a solicitação de pull está desbloqueada (opcional)
Se você tiver mesmo resultados impeditivos, depois que tiver corrigido ou descartado os resultados relevantes, retorne à seção Verificações na parte inferior da pull request.
Em nosso exemplo, com as ocorrências Erro e Aviso resolvidas, o banner de bloqueio da mesclagem desaparece. A pull request agora está pronta para ser mesclada.
Se a faixa ainda estiver lá, isso significará que um resultado em ou acima de gravidade impeditiva ainda está aberta.
Como isso se relaciona com o restante da saúde do código
O pull request que você acabou de aprovar faz parte de um contexto mais amplo:
- Pontuações. As pontuações de confiabilidade e capacidade de manutenção do seu repositório são calculadas com base nas ocorrências identificadas no branch padrão. A resolução dos resultados antes da mesclagem é como você evita que essas pontuações se deteriorem. Consulte Referência de métricas e pontuações.
- Pendências. Qualquer coisa que você não corrija na pull request entra na lista de pendências na ramificação padrão. Reduzir esse backlog exige uma disciplina própria. Consulte Elevando a pontuação de qualidade do código do repositório.
- Conformidade. Quando uma classe de resultados não deve alcançar genuinamente a ramificação padrão, o conjunto de regras "Exigir resultados da qualidade de código" ajuda administradores de repositório e proprietários de organização a codificar essa decisão como uma porta de mesclagem. Consulte Resolvendo um bloqueio em sua pull request.
As equipes mais saudáveis combinam todas as três: triagem e remediação deliberadas na etapa de pull request, trabalho periódico na lista de pendências e limites aplicados no limite de mesclagem.
Solução de problemas
- Não vejo comentários Code Quality . A verificação talvez ainda esteja em execução, suas alterações podem não afetar um idioma compatível ou você não tem nenhum resultado. Confirme se Code Quality está habilitado e dê tempo para que a verificação (chamada "CodeQL – Qualidade do Código") seja concluída. Consulte Habilitando o GitHub Code Quality.
- Não encontro correções automáticas para meus problemas de qualidade de código. A geração de correção automática consome GitHub AI Credits. Sua organização pode ter esgotado seu orçamento mensal de AI credits.
- O banner do bloco de merge não desaparece. Pelo menos um resultado em ou acima da gravidade de bloqueio ainda está aberto. Se você não vir um nível de severidade definido no banner de bloqueio de mesclagem, isso significa que seu repositório está usando os limites de qualidade de código mais rigorosos, que exigem que todos os problemas sejam resolvidos antes da mesclagem. Consulte Resolvendo um bloqueio em sua pull request.
Conclusion
Neste tutorial, você percorreu Code Quality comentários sobre uma pull request, usou gravidade para priorizar a correção e resolveu deliberadamente cada problema identificado antes de mesclar a pull request. Ao tratar cada resultado, e a correção automática, como uma decisão pequena contextual, você impediu que a dívida de qualidade do código chegasse à ramificação padrão.
Próximas Etapas
- Aplique o mesmo pensamento à sua lista de pendências existente: Elevando a pontuação de qualidade do código do repositório.
- Saiba como as descobertas se traduzem em pontuações para que você possa medir o impacto do trabalho: Referência de métricas e pontuações.