Introdução
Neste tutorial, você trabalhará em um backlog de Code Quality resultados na sua branch padrão, irá priorizá-los por risco, resolverá os resultados de maior impacto e comunicará o resultado às partes interessadas. O que você aprenderá:
- Como ler o painel e entender o que suas pontuações significam.
- Como priorizar a remediação e decidir se deve aplicar uma correção automática, delegar para agente de nuvem Copilot ou descartar uma ocorrência.
- Como comunicar o impacto do trabalho de correção.
- Quais medidas adicionais você pode tomar para evitar que a pendência volte a crescer.
Este é um tutorial guiado, portanto prioriza a compreensão em vez da velocidade. Para conhecer as etapas básicas para gerar uma correção automática ou dispensar um achado, consulte o guia complementar: Corrigindo os problemas de qualidade do código apontados no backlog do seu repositório.
Antes de começar
- Code Quality está habilitado em um repositório que você possui ou mantém. Consulte Habilitando o GitHub Code Quality.
- Se você tiver habilitado Code Quality recentemente, aguarde alguns minutos para que a verificação inicial CodeQL do branch padrão seja concluída.
Ao longo deste tutorial, usaremos um exemplo em execução: um repositório cujo painel atualmente mostra pontuações de "Confiabilidade: Ruim" e "Manutenção: Justa" para a qualidade do código.
Etapa 1: Avaliar sua pontuação atual
- Navegue até a Security and quality guia do repositório.
- Clique para expandir Qualidade do código, e clique em Descobertas padrão.
Aqui você verá as pontuações de Confiabilidade e Manutenção.
Essas pontuações são calculadas com base nos resultados da sua ramificação padrão:
| Métrica | Definition | Descobertas de exemplo |
|---|---|---|
| Reliability | Avalie se o código executa a função pretendida corretamente, previsível e consistentemente. O código confiável é livre de bugs (erros), lida com erros com segurança e opera conforme o esperado em condições normais e de limite. | Problemas com desempenho, simultaneidade, tratamento de erros, correção |
| Facilidade de manutenção | Avalie como é fácil entender, modificar e estender o código ao longo do tempo. O código mantenedível segue as práticas recomendadas, evita a complexidade desnecessária e é organizado para facilitar as alterações futuras e a colaboração. | Código não utilizado/morto, legibilidade, complexidade, nomenclatura conflitante, separação ruim de preocupações |
Cada pontuação é determinada pela gravidade mais alta da constatação ainda presente nessa métrica. Para elevar a pontuação, você precisa resolver cada achado no nível de severidade mais alto no momento.
Em nosso exemplo, Confiabilidade é "Baixa" porque ainda há achados de nível Erro que afetam a confiabilidade. Avisos e Observações merecem atenção, mas, até que os Erros sejam corrigidos, eles não poderão alterar a pontuação.
Etapa 2: Ler a lista por regra e focar nas descobertas de maior impacto
Na exibição Descobertas padrão, os resultados são agrupados por regra. Isso é útil para entender porque uma única regra com muitas descobertas pode refletir um hábito de codificação repetido. Depois de compreender uma ocorrência, pode ser mais fácil entender as correções automáticas propostas para todas elas, o que torna a remediação mais rápida e mais fácil de revisar em massa.
Além disso, procure regras que completem um nível de severidade de uma de suas pontuações — se a correção de uma regra remover o último "Erro" restante que afeta a Confiabilidade, sua pontuação subirá imediatamente.
Em nosso exemplo, uma regra — “Propriedade substituída” — responde por 40 das 128 ocorrências, e todas as 40 são de nível Erro. Limpar isso removeria todos os achados de nível Erro que afetam a Confiabilidade, o que elevaria nossa pontuação para a próxima faixa.
Etapa 3: Corrigir as constatações
Depois de escolher uma regra, decida como lidar com cada descoberta:
| Assessment | Ação recomendada | Notes |
|---|---|---|
| A descoberta é legítima. | Clique em Gerar correção e abra uma solicitação de pull | Ao clicar em Gerar correção, consome AI credits. Você pode adicionar vários autofixos ao mesmo branch para agrupar o trabalho de correção em uma solicitação de pull. |
| O resultado não se aplica. Por exemplo, está em código legado, segue um padrão intencional ou é um falso positivo | Clique em Ignorar. | O achado é considerado resolvido e removido da lista de descobertas abertas. |
Em nosso exemplo, geramos correções automáticas para as 40 ocorrências de "propriedade sobrescrita" e abrimos um pull request. Como eles compartilham um único padrão, as correções são quase idênticas. Mesclamos a solicitação de pull quando as verificações de CI são aprovadas.
Etapa 4: Comunicar o impacto
Depois de mesclar a correção, retorne ao modo de exibição e captura "Descobertas padrão":
- A pontuação que mudou. Por exemplo, Confiabilidade: Má → Justa.
- O requisito que o desbloqueou. Por exemplo, todas as descobertas no nível de erro que afetam a confiabilidade agora foram resolvidas.
- A redução dos resultados abertos. Por exemplo, de 128 abertos a 88.
Em nosso exemplo, remover a regra "Propriedade sobrescrita" faz a Confiabilidade passar de Ruim para Regular — a primeira melhora na pontuação que a equipe pode apontar.
Como isso se relaciona com o restante da saúde do código
Cada descoberta que você resolveu hoje pode reaparecer amanhã se novas solicitações de pull introduzirem os mesmos tipos de problema. Para interromper a regeneração da lista de pendências:
- Defina um limite de mesclagem em seu branch padrão para bloquear solicitações de pull que introduzem novas descobertas de qualidade de código. Consulte Definindo limites de qualidade de código para solicitações de pull.
- Corrija as descobertas na solicitação de pull quando elas aparecem. Consulte Impedindo que problemas de qualidade de código atinjam seu branch padrão.
Solução de problemas
- A pontuação não mudou após mesclar as correções. Pelo menos uma localização no nível de gravidade mais alto atual para essa métrica ainda está aberta.
- A verificação não foi executada novamente. Code Quality as verificações são executadas automaticamente após cada push para o branch padrão. Aguarde alguns minutos para que o fluxo de trabalho seja concluído.
Conclusion
Neste tutorial, você avaliou as pontuações de qualidade do seu repositório, priorizou os itens do backlog por severidade e regra, resolveu os problemas identificados usando correções automáticas e comunicou o resultado na forma de evolução da pontuação.
Próximas Etapas
- Reduza ainda mais a dívida técnica corrigindo descobertas em arquivos alterados recentemente. Consulte Corrigindo descobertas de qualidade de código em arquivos mesclados recentemente.