Introdução
Neste tutorial, você acompanhará um único pull request pela análise do Code Quality, do primeiro comentário até a mesclagem. O que você aprenderá:
- Como ler os comentários em uma Code Quality pull request e distinguir os dois tipos de apontamento.
- 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 um pull request afetam a pontuação, o backlog e os critérios de mesclagem do seu repositório.
Ao final, você terá resolvido cada problema impeditivo na pull request de exemplo e feito o merge com a 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 aplicar 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 um pull request aberto para a branch padrão com pelo menos um achado 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á. Uma verificação Code Quality foi realizada automaticamente no pull request e relatou vários problemas na forma de 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 achados na etapa do pull request significa que sua equipe gasta menos tempo priorizando o trabalho de correção em vez do desenvolvimento de funcionalidades e evita a sobrecarga de pull requests extras apenas para reduzir o backlog.
Etapa 1: Encontre os comentários na sua Code Quality pull request
Quando você abre uma solicitação pull, Code Quality executa dois tipos de análise e posta descobertas como comentários. Abra a guia Arquivos alterados do seu pull request e veja quem deixou cada comentário — o autor informa qual é o tipo de achado.
-
As descobertas baseadas em regras são postadas pelo
github-code-quality[bot]. Code Quality usa CodeQL para verificar suas alterações em relação a um conjunto de regras e cada comentário inclui um autofixo sugerido. -
As descobertas de IA são postadas por Copilot. Se sua organização tiver licenças Copilot e os recursos de IA estiverem habilitados para sua empresa, Revisão de código do Copilot identifica problemas de qualidade que a análise baseada em regras pode não detectar. Esses comentários também incluem uma correção automática sugerida.
Em nosso exemplo, examinaremos três comentários provenientes github-code-quality[bot], portanto, são descobertas baseadas em regras. No seu próprio pull request, você poderá ver os dois tipos — observe qual é qual antes de prosseguir, porque os rótulos de severidade (Etapa 2) se aplicam somente aos comentários baseados em regras.
Etapa 2: Ler o rótulo de severidade para decidir o que importa
Cada descoberta baseada em regras de github-code-quality[bot] recebe um rótulo de gravidade — 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 um bloqueio está ativo, role até a seção Verificações na parte inferior do 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", portanto, a faixa está presente: o Erro e o Aviso estão bloqueando 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 de bloco de mesclagem não especificar um nível de gravidade, você deverá limpar todas as descobertas para mesclar sua solicitação de pull.
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 Aplicar sugestão não consome AI credits, e as correções automáticas baseadas em regras não exigem licença Copilot. | |
| 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 o branch do pull request | Requer uma Copilot licença e consome AI credits. | |
| O achado não se aplica, por exemplo, trata-se de código de teste, um padrão intencional ou um falso positivo. | Clique em Descartar resultado e forneça um motivo | Você poderá mesclar seu pull request, mas o alerta aparecerá no backlog do repositório e em pull requests futuras. |
Aplique isso ao seu próprio pull request, seguindo a ordem de severidade.
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. As ocorrências são resolvidas e deixam de ser contabilizadas na contagem de bloqueios.
- Uma localização no nível de anotação sinaliza um padrão secundário em um auxiliar de teste adjacente. É intencional, então descartamos com um motivo como "Usado em testes".
- Há vários achados adicionais no nível de Nota. Em vez de analisar cada sugestão de correção automática, uma por uma, fazemos o seguinte comentário: "
@copilot, corrija todos os problemas restantes de nível Note". Acompanhamos o progresso de Copilot na guia Agentes do repositório e revisamos os commits que ele envia para a pull request quando estão prontos.
Etapa 4: confirmar se a solicitação de pull está desbloqueada (opcional)
Se você de fato tiver problemas bloqueadores, depois de corrigir ou descartar os problemas relevantes, volte para a seção Checks na parte inferior do pull request.
Em nosso exemplo, com as ocorrências Erro e Aviso resolvidas, o banner de bloqueio da mesclagem desaparece. Sua pull request agora pode ser mesclada.
Se o banner ainda estiver lá, isso significa que um achado com severidade de bloqueio ou superior ainda está em aberto.
Etapa 5: Solucione os resultados gerados por IA de Copilot
Se sua organização tiver Copilot licenças e os recursos de IA estiverem habilitados para sua empresa, você também verá comentários postados por Copilot. Estas são as descobertas baseadas em IA introduzidas na Etapa 1, e elas vêm de Revisão de código do Copilot em vez de github-code-quality[bot].
Quando os resultados baseados em regras comparam suas alterações com um conjunto fixo de CodeQL regras, Revisão de código do Copilot raciocina sobre a intenção do seu código. Ele identifica problemas de qualidade que não se enquadram em uma regra específica, por isso, é um complemento útil para os comentários baseados nas regras, e não um substituto para eles.
Essas descobertas não carregam um rótulo de severidade de "Erro", "Aviso" ou "Observação". Como o portão de mesclagem que você viu na Etapa 2 conta apenas a gravidade das descobertas baseadas em regras, as descobertas baseadas em IA nunca bloqueiam sua solicitação de pull por conta própria. Isso não os torna opcionais; resolvê-los dentro do contexto ainda é a melhor forma de manter os problemas de qualidade fora do branch principal.
Você resolve uma descoberta com tecnologia de IA com as mesmas três opções que usou na Etapa 3:
- Aplique a sugestão de correção automática. Cada comentário inclui uma correção sugerida. Se estiver correto as-is, clique em Confirmar sugestão. Aplicar a correção automática não consome GitHub AI Credits.
- Delegar para Copilot— mencione
@copilotem um comentário para entregar o trabalho ao agente de nuvem. Copilot interage com 👀, inicia uma nova sessão de agente e envia as correções necessárias no branch do pull request. Essa opção requer uma Copilot licença e consome GitHub AI Credits. - Resolva o comentário. Se ele não se aplicar ao código, clique em Resolver.
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. Resolver os achados antes da mesclagem é assim que você evita que essas pontuações se deteriorem. Consulte Referência de métricas e pontuações.
- Pendências. Qualquer achado que você não corrigir no pull request entra para o backlog de achados na branch 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 descobertas genuinamente não deve alcançar o branch padrão, o conjunto de regras "Exigir resultados de qualidade de código" ajuda os administradores do repositório e os proprietários da 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 estas três práticas: triagem e remediação deliberadas na etapa do pull request, trabalho periódico no backlog e limiares aplicados no ponto de merge.
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.
- Eu só vejo comentários de
github-code-quality[bot], nunca de Copilot. As descobertas alimentadas por IA exigem Copilot licenças e recursos de IA habilitados para sua empresa. Sem eles, você verá apenas descobertas baseadas em regras. - 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 achado no nível de severidade de bloqueio ou acima continua em 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ê analisou os comentários em uma Code Quality solicitação de pull, usou a severidade para priorizar a correção e resolveu deliberadamente cada problema identificado antes de mesclar sua solicitação de pull. Ao tratar cada problema identificado e sua correção automática como uma pequena decisão contextual, você impediu que a dívida de qualidade do código chegasse ao seu ramo 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.