Introducción
En este tutorial, seguirás una única pull request a través del análisis de Code Quality, desde el primer comentario hasta la fusión. Aprenderá lo siguiente:
- Cómo leer los Code Quality comentarios en una solicitud de extracción y distinguir los dos tipos de hallazgo.
- Cómo usar la etiqueta de gravedad de un hallazgo para decidir qué corregir, qué descartar y en qué orden.
- Cómo las opciones que realice en una solicitud de incorporación de cambios dan forma a las puntuaciones, trabajos pendientes y puertas de combinación del repositorio.
Al final, habrás resuelto todas las incidencias bloqueantes en el pull request de ejemplo y lo habrás fusionado con la comprobación Code Quality correcta, y comprenderás por qué tomaste cada decisión.
Esta es una guía paso a paso, por lo que prioriza la comprensión frente a la rapidez. Para consultar los pasos básicos para aplicar una corrección automática o descartar un hallazgo, consulte la guía complementaria: Corregir las incidencias de calidad del código en una pull request.
Antes de comenzar
- Code Quality está habilitado en un repositorio al que contribuye. Consulte Habilitar GitHub Code Quality.
- El repositorio usa un lenguaje compatible con CodeQL para que se generen resultados y puntuaciones basados en reglas. Para obtener una lista de los idiomas admitidos, consulte Calidad del código de GitHub.
- Tiene abierta una solicitud de extracción contra la rama predeterminada con al menos un Code Quality hallazgo por clasificar. Si no tiene lista una solicitud de incorporación de cambios, puede seguir el ejemplo siguiente.
A lo largo de este tutorial, usaremos un ejemplo recurrente: una solicitud de incorporación de cambios que refactoriza parte del código introducirá varios problemas de calidad del código en la rama predeterminada si se fusiona tal como está. Un Code Quality examen se ha ejecutado automáticamente en la solicitud de incorporación de cambios y ha notificado varios resultados como comentarios.
¿Por qué la solicitud de incorporación de cambios es el mejor lugar para corregir una búsqueda?
Cada hallazgo que no resuelves en la fase de pull request se convierte en una tarea pendiente en la lista de tareas del repositorio, y la deuda técnica suele ser más costosa de saldar más adelante que de abordar ahora. Ahora mismo, mientras la pull request sigue abierta, todavía tienes fresco en la mente el contexto y la intención del código, lo que hace que sea más rápido evaluar, aplicar o descartar con confianza cada hallazgo y su corrección automática.
Resolver los hallazgos en la fase de pull request significa que el equipo dedica menos tiempo a priorizar las tareas de corrección frente al desarrollo de nuevas funcionalidades y evita la sobrecarga de tener que crear pull requests adicionales solo para reducir el backlog.
Paso 1: Buscar los comentarios en la Code Quality solicitud de incorporación de cambios
Al abrir una solicitud de incorporación de cambios, Code Quality ejecuta dos tipos de análisis y publica resultados como comentarios. Abra la pestaña Archivos cambiados de la solicitud de incorporación de cambios y examine quién dejó cada comentario: el autor le indica qué tipo de búsqueda es.
-
Los resultados basados en reglas se publican en .
github-code-quality[bot]Code Quality usa CodeQL para analizar tus cambios según un conjunto de reglas, y cada comentario incluye una corrección automática sugerida. -
Los hallazgos con tecnología de inteligencia artificial se publican mediante Copilot. Si su organización tiene licencias de Copilot y las funciones de IA están habilitadas para su empresa, revisión de código Copilot busca problemas de calidad que el análisis basado en reglas puede pasar por alto. Estos comentarios también incluyen una corrección automática sugerida.
En nuestro ejemplo, veremos tres comentarios que proceden de github-code-quality[bot], por lo que son conclusiones basadas en reglas. En su propia solicitud de extracción, puede ver ambos tipos; observe cuál es cuál antes de continuar, porque las etiquetas de severidad (Paso 2) solo se aplican a los comentarios basados en reglas.
Paso 2: Leer la etiqueta de gravedad para decidir qué importa
Cada búsqueda basada en reglas de github-code-quality[bot] incluye una etiqueta de gravedad: Error, Advertencia o Nota. Busque la etiqueta en uno de los comentarios y compruébalo en esta tabla.
| Severity | Definición |
|---|---|
| Error | Indica un problema de alta gravedad que es probable que cause errores, errores o riesgos de mantenimiento importantes. |
| Advertencia | Indica un problema de gravedad moderada que puede afectar a la calidad o confiabilidad del código, pero no es inmediatamente crítico. |
| Nota | Indica un problema de gravedad baja, una mejora menor o una recomendación. Estos hallazgos son útiles para la salud y el mantenimiento continuos del código. |
La etiqueta cumple dos funciones para ti a la vez:
- Le indica qué corregir primero. La gravedad refleja el impacto esperado de una regla en el código típico. En nuestro ejemplo, empezarías con el Error, después con la Warning, y tratarías la Note como un refinamiento opcional.
- Puede determinar si siquiera puede fusionar. Un administrador de repositorio o propietario de la organización puede configurar Code Quality como puerta de combinación. Por ejemplo, si el umbral para fusionar es "Advertencia y superior", todos los hallazgos de nivel AdvertenciayError deben corregirse o descartarse antes de poder fusionar (los hallazgos de Nota no impedirían la fusión). Del mismo modo, un umbral más estricto puede requerir que resuelva todos los resultados antes de la combinación.
Para ver si una puerta está en vigor, desplácese hasta la sección Comprobaciones en la parte inferior de la solicitud de incorporación de cambios. Si tus cambios están por debajo del umbral requerido, verás un banner de bloqueo de fusión: "La fusión está bloqueada: se detectaron problemas de calidad del código".
En nuestro ejemplo, la puerta se establece en "Advertencia y versiones posteriores", por lo que el banner está presente: el error y la advertencia bloquean la combinación y la nota no. Esto te indica lo que tienes que resolver antes de poder fusionar esta pull request.
Si el aviso de bloqueo de la fusión no especifica un nivel de gravedad, debes resolver todos los hallazgos para poder fusionar tu solicitud de incorporación de cambios.
Paso 3: Resolver cada búsqueda
Para cada hallazgo, decida si se aplica a su código y, si es así, cómo corregirlo. Esto le lleva a una de estas tres acciones.
| Assessment | Acción recomendada | Notas |
|---|---|---|
| El hallazgo es válido y la corrección sugerida parece correcta. | ||
| Aplica la sugerencia de autocorrección | Al hacer clic en Aceptar sugerencia, no se consumen AI credits y las correcciones automáticas basadas en reglas no requieren una licencia Copilot. | |
| El hallazgo es real, pero quieres corregir varios a la vez, o la corrección sugerida necesita adaptarse | ||
Delegar en Copilot: mencione @copilot en un comentario para entregar el trabajo al agente en la nube. | ||
| Copilot reacciona con 👀, inicia una nueva sesión del agente e inserta las correcciones necesarias en la rama de la solicitud de incorporación de cambios. | Requiere una licencia Copilot y consume AI credits. | |
| El hallazgo no se aplica; por ejemplo, se trata de código de prueba, un patrón intencional o un falso positivo. | Haga clic en Descartar búsqueda y proporcione un motivo. | Podrás fusionar tu solicitud de cambios, pero el hallazgo aparecerá en la lista de tareas pendientes del repositorio y en las futuras solicitudes de cambios. |
Aplique la práctica a su propia solicitud de incorporación de cambios, trabajando en orden de gravedad.
En nuestro ejemplo:
- Los hallazgos de nivel Error y Warning son fallos reales y las correcciones automáticas sugeridas parecen razonables, por lo que aplicamos dichas correcciones automáticas. Los hallazgos se resuelven y dejan de contabilizarse en el recuento de bloqueos.
- Un hallazgo de nivel Note señala un patrón menor en una utilidad auxiliar de prueba adyacente. Es intencional, por lo que lo descartamos con un motivo como "Se usa en las pruebas".
- Hay varios hallazgos adicionales en el nivel de nota. En lugar de revisar cada sugerencia de corrección automática una por una, escribimos: "
@copilot, corrige todas las incidencias restantes de nivel Nota". Realizamos un seguimiento Copilotdel progreso de la pestaña Agentes del repositorio y revisamos las confirmaciones que inserta en la solicitud de incorporación de cambios cuando estén listos.
Paso 4: Confirmar que la solicitud de incorporación de cambios está desbloqueada (opcional)
Si tiene resultados de bloqueo, una vez corregido o descartado los resultados pertinentes, vuelva a la sección Comprobaciones en la parte inferior de la solicitud de incorporación de cambios.
En nuestro ejemplo, con los resultados error y advertencia resueltos, el banner del bloque de combinación desaparece. Tu pull request ya está lista para fusionarse.
Si el banner sigue estando ahí, significa que una búsqueda en o por encima de la gravedad de bloqueo sigue abierta.
Paso 5: Resolución de los resultados con tecnología de inteligencia artificial a partir de Copilot
Si su organización tiene Copilot licencias y las características de IA están habilitadas para su empresa, también verá los comentarios publicados por Copilot. Estos son los hallazgos impulsados por IA introducidos en el Paso 1, y proceden de revisión de código Copilot en lugar de github-code-quality[bot].
Mientras que los hallazgos basados en reglas comparan tus cambios con un conjunto fijo de reglas CodeQL, revisión de código Copilot razona sobre la intención de tu código. Detecta problemas de calidad que no se asignan a una regla específica, por lo que es un complemento útil para los comentarios basados en reglas en lugar de reemplazarlos.
Estos hallazgos no contienen una etiqueta de gravedad de "Error", "Advertencia" o "Nota". Dado que la puerta de combinación que vio en el paso 2 solo cuenta la gravedad de los hallazgos basados en reglas, los hallazgos con tecnología de inteligencia artificial nunca bloquean la solicitud de incorporación de cambios por su cuenta. Esto no hace que sean opcionales, resolverlos en contexto sigue siendo el lugar óptimo para mantener los problemas de calidad fuera de la rama predeterminada.
Resuelva una búsqueda con tecnología de inteligencia artificial con las mismas tres opciones que usó en el paso 3:
- Aplique la sugerencia de corrección automática. Cada comentario incluye una corrección sugerida. Si es correcto as-is, haga clic en Confirmar sugerencia. Aplicar la corrección automática no consume GitHub AI Credits.
- Delegar en Copilot: mencione
@copiloten un comentario para entregar el trabajo al agente en la nube. Copilot reacciona con 👀, inicia una nueva sesión del agente y sube las correcciones necesarias a la rama de la pull request. Esta opción requiere una Copilot licencia y consume GitHub AI Credits. - Resuelva el comentario. Si no se aplica al código, haga clic en Resolver.
Cómo se relaciona esto con el resto de la salud de tu código
La solicitud de extracción que acaba de aprobar forma parte de algo más amplio:
- Puntuaciones. Las puntuaciones de confiabilidad y mantenimiento del repositorio se calculan a partir de los resultados de la rama predeterminada. Resolver los resultados antes de combinar es cómo evitar que esas puntuaciones se desfasen. Consulte Referencia de métricas y puntuaciones.
- Trabajo pendiente. Todo lo que no corrijas en la solicitud de extracción se añade al trabajo pendiente de hallazgos de la rama predeterminada. Reducir ese trabajo acumulado es una disciplina en sí misma. Consulte Aumentar la puntuación de calidad del código de su repositorio.
- Cumplimiento. Cuando una clase de resultados realmente no debe alcanzar la rama predeterminada, el conjunto de reglas "Requerir resultados de calidad de código" ayuda a los administradores del repositorio y a los propietarios de la organización a codificar esa decisión como una puerta de combinación. Consulte Resolución de un bloqueo en la solicitud de extracción.
Los equipos más saludables combinan las tres: triaje deliberado y subsanación en la fase de la pull request, trabajo periódico en el backlog y umbrales obligatorios en el momento de la fusión.
Troubleshooting
- No veo ningún Code Quality comentario. Es posible que el análisis siga ejecutándose, que sus cambios no afecten a un idioma compatible o que no tenga ningún hallazgo. Confirme Code Quality que está habilitado y proporcione la hora de finalización de la comprobación (denominada "CodeQL: calidad del código"). Consulte Habilitar GitHub Code Quality.
- Sólo veo comentarios de
github-code-quality[bot], nunca de Copilot. Los hallazgos con tecnología de inteligencia artificial requieren Copilot licencias y características de IA habilitadas para su empresa. Sin ellos, solo verá conclusiones basadas en reglas. - No veo correcciones automáticas para mis hallazgos de calidad del código. La generación de autofijos GitHub AI Creditsconsume . Es posible que su organización haya agotado su presupuesto mensual de AI credits.
- El aviso de bloqueo de combinación no desaparece. Al menos un hallazgo con severidad de bloqueo o superior sigue abierto. Si no ves un nivel de gravedad definido en el aviso de bloqueo de fusión, significa que tu repositorio utiliza los umbrales de calidad de código más estrictos, lo que exige resolver todos los hallazgos antes de la fusión. Consulte Resolución de un bloqueo en la solicitud de extracción.
Conclusión
En este tutorial, has trabajado con comentarios en una solicitud de extracción de cambios Code Quality, has utilizado la gravedad para priorizar la subsanación y has resuelto intencionadamente cada hallazgo antes de fusionar tu solicitud de extracción de cambios. Al tratar cada hallazgo y su corrección automática como una pequeña decisión en contexto, evitaste que la deuda de calidad del código llegara a tu rama predeterminada.
Pasos siguientes
- Aplique el mismo pensamiento a su trabajo pendiente existente: Aumentar la puntuación de calidad del código de su repositorio.
- Obtenga información sobre cómo los resultados se traducen en puntuaciones para que pueda medir el impacto del trabajo: Referencia de métricas y puntuaciones.