Introdução
Neste tutorial, você vai trabalhar em uma lista de pendências de Code Quality resultados na ramificação padrão, priorizar por risco, resolver os resultados de mais impacto e informar o resultado a stakeholders. O que você aprenderá:
- Como ler o painel e entender o que suas pontuações significam.
- Como priorizar a correção e decidir se é necessário aplicar uma correção automática, delegar para agente de nuvem Copilot ou descartar um resultado.
- 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 saber as etapas básicas da geração de uma correção automática ou dispensar um resultado, 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 o exame inicial CodeQL da ramificação padrão seja concluído.
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 do resultado ainda presente para essa métrica. Para elevar a pontuação, você precisa resolver cada achado no nível de gravidade 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 podem 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" – é responsável por 40 dos 128 resultados, e todos os 40 são no nível Erro. Limpar isso removeria todos os resultados no nível Erro que afetam a Confiabilidade, o que moveria nosso escopo até 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árias correções automáticas na mesma ramificação para agrupar o trabalho de correção em uma pull request. |
| 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 os 40 resultados de "Propriedade substituta" e abrimos uma pull request. Como eles compartilham um único padrão, as correções são quase idênticas. Mesclamos a pull request assim que as verificações de CI são aprovadas.
Etapa 4: Comunicar o impacto
Depois que você tiver mesclado a correção, retorne à exibição "Descobertas padrão" e capture:
- 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 de resultados abertos.** Por exemplo, *de 128 abertos para 88*.
Em nosso exemplo, a remoção da regra "Propriedade substituída" faz a Confiabilidade passar de Ruim para Regular – a primeira melhoria na pontuação para a qual 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 um resultado no nível de gravidade mais alto atual dessa métrica ainda está aberto.
- A verificação não foi executada novamente. Os exames Code Quality serão executados automaticamente depois de cada push para a ramificação 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.