Introducción
En este tutorial, seguirá una única solicitud de incorporación de cambios a través del análisis de Code Quality, desde el primer comentario hasta la fusión. Aprenderá lo siguiente:
- Cómo leer los comentarios en la Code Quality solicitud de incorporación de cambios.
- 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 elija 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 incorporación de cambios contra la rama predeterminada con al menos un hallazgo de Code Quality 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 examen de Code Quality 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 de Code Quality en la solicitud de incorporación de cambios
Al abrir una solicitud de incorporación de cambios, Code Quality usa CodeQL para examinar los cambios en un conjunto de reglas y publica resultados como comentarios por github-code-quality[bot]. Cada comentario incluye un autofijo sugerido. Abra la pestaña Archivos modificados de la solicitud de incorporación de cambios para revisar los resultados.
En nuestro ejemplo, veremos tres comentarios de github-code-quality[bot]. Tenga en cuenta las etiquetas de gravedad de cada una. En el paso 2 se explica lo que significan.
Paso 2: Leer la etiqueta de gravedad para decidir qué importa
Cada búsqueda de contiene una etiqueta de github-code-quality[bot] 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 se puede llevar a cabo la combinación o no. 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 como "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 banner de bloqueo de la combinación no especifica un nivel de gravedad, debe resolver todos los hallazgos para poder combinar su 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 Confirmar sugerencia no se consume AI creditsy los autofijos no requieren una Copilot licencia. | |
| 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 todos los hallazgos restantes de nivel Nota". Realizamos un seguimiento del progreso de Copilot en 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 un hallazgo con ese nivel de gravedad de bloqueo o con uno superior sigue abierto.
Cómo se relaciona esto con el resto de la salud de tu código
La solicitud de incorporación de cambios 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 corrija en la solicitud de incorporación de cambios se añadirá 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 en mejor estado combinan las tres: triaje deliberado y subsanación en la fase de la solicitud de incorporación de cambios, trabajo periódico pendiente y umbrales obligatorios en el momento de la combinació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.
- No veo correcciones automáticas para mis hallazgos de calidad del código. La generación de correcciones automáticas consume GitHub AI Credits. 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 gravedad 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, ha trabajado con comentarios de Code Quality en una solicitud de incorporación de cambios, ha utilizado la gravedad para priorizar la subsanación y ha resuelto intencionadamente cada hallazgo antes de combinar su solicitud de incorporación de cambios. Al tratar cada hallazgo y su corrección automática como una pequeña decisión en contexto, ha evitado que la deuda de calidad del código llegara a su 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.