Manual del Revisor

El modelo operativo para revisar PR y gestionar incidencias. Dimensionado para mantener una alta calidad de revisión bajo un volumen elevado; enruta por riesgo para que las rutas de alto impacto reciban la atención necesaria sin arrastrar cada cambio menor a través del mismo filtro.

Para la secuencia real de obtención y los mecanismos de veredicto de revisión, consulta el Protocolo de revisión de PR. Esta página es el modelo operativo; el protocolo es el procedimiento.

Rutas rápidas

Utiliza esta sección para dirigir una revisión antes de leer más a fondo. Cada fila enlaza a la sección que lo desarrolla.

Usa PR lanes para las expectativas de enrutamiento; usa la matriz de riesgo de este playbook para la profundidad de la revisión.

Matriz de profundidad de revisión

domain:security sigue siendo independiente de risk:*: úsala para un límite efectivo de seguridad o confianza, no simplemente porque el componente modificado esté relacionado con la seguridad. Cualquiera de las dos etiquetas activa la misma ruta de revisión exhaustiva y de dos aprobaciones independientes del Core Team. La revisión automatizada no cuenta como una aprobación del Core Team.

Cuando haya dudas, clasifica en la categoría superior y pide a un mantenedor que resuelva el límite antes de fusionar.

Las etiquetas de riesgo son actualmente manuales. #9345 mantiene cualquier clasificador de riesgo futuro en modo de solo informe hasta que los mantenedores habiliten la mutación por separado. Sigue el contrato de automatización de etiquetas: risk:manual congela el reemplazo automatizado del riesgo cuando deba persistir una corrección del mantenedor, pero nunca reduce el requisito de revisión o aprobación.

Las etiquetas son metadatos del mantenedor. Si la etiqueta correcta es obvia y tienes permiso, corrígela tú mismo antes de finalizar la revisión. Pregunta al autor solo cuando la elección correcta de la etiqueta sea ambigua o no haya nadie con permisos sobre las etiquetas disponible.

Flujo de trabajo estándar

Toma de datos de cinco minutos

Para cada nuevo PR, antes de leer cualquier código:

1. Confirma que la plantilla del PR esté completa: resumen, evidencia de validación, seguridad y privacidad, compatibilidad, y rollback (para casos de media/alta prioridad).
2. Confirmar que las etiquetas estén presentes y sean plausibles: size:*, risk:*, etiquetas de alcance, nivel de contribuidor cuando corresponda.
3. Confirme el estado de la señal CI Required Gate.
4. Confirmar que el alcance es una preocupación. Las PRs masivas con características mixtas se devuelven para su división, a menos que la mezcla esté explícitamente justificada.
5. Confirma las reglas de privacidad / higiene de datos. Consulta Privacidad para el manual completo de reglas.
6. Si el PR cambia la presentación visual, confirma que el autor probó la interfaz compatible real y proporcionó capturas de pantalla que protejan la privacidad en dimensiones representativas. Una declaración de que no se realizó la prueba de humo deja constancia de la carencia, pero no la subsana.

Si alguna verificación de admisión falla, deja un comentario con una lista de verificación accionable y detente. No hagas una revisión profunda de un PR que no haya pasado la admisión: el intercambio de idas y vueltas es más barato en esta capa que después de haber analizado el diff.

Lista de verificación de carril rápido (cada PR)

• El límite del alcance es explícito y creíble.
• Los cambios de comportamiento se comprueban frente al contrato que los controla: documentos de arquitectura, módulos fuente de referencia, límites de traits, pruebas existentes, la forma de la API pública, comentarios del código fuente o decisiones explícitas de los mantenedores.
• La procedencia del cuerpo del PR es verdadera. Los RFC, auditorías, issues, PR, rutas, artefactos generados o hallazgos de seguimiento citados existen y respaldan la afirmación.
• La evidencia de validación nombra las comprobaciones en las que se confía y por qué cubren el comportamiento modificado.
• Las afirmaciones directamente observables por el usuario identifican el límite del usuario y proporcionan la evidencia más pequeña y creíble que lo alcanza; utiliza User-boundary proof cuando la evidencia de unidad, simulada, de compilación o de CI genérica no sea suficiente.
• Los cambios de presentación visual incluyen pruebas de la interfaz real correspondientes a una revisión identificable, además de capturas de pantalla con suficiente contexto del diseño circundante para evaluar el resultado. Las aserciones de cadenas, las instantáneas que solo contienen el componente y las pruebas del renderizador a nivel de helper no pueden sustituir esta evidencia. Las afirmaciones sobre interacciones y transiciones también especifican la acción del usuario y el resultado observado.
• No se requiere duplicar el Cargo local cuando la CI obligatoria reciente cubre el mismo head, target y conjunto de características. Pide validación adicional solo cuando corresponda a una laguna nombrada en la puerta obligatoria, como pruebas de macOS/Windows, Clippy multiplataforma, cobertura de escritorio, compilaciones de destino de lanzamiento, CI obsoleta o CI no disponible.
• Los cambios en el comportamiento visible para el usuario están documentados.
• El autor demuestra comprensión del comportamiento y del alcance del impacto (especialmente en PRs asistidos por IA).
• La ruta de rollback es concreta; “revert” no es concreto.
• La compatibilidad y el impacto de la migración son claros.
• MSRV, la toolchain fijada, u otros cambios en el umbral de versiones se señalan como que afectan la compatibilidad: la PR explica quién debe actualizar, las líneas base de CI y del instalador coinciden, y las notas de la versión nombran el nuevo umbral cuando el cambio puede afectar a quienes compilan desde el código fuente.
• No se filtraron datos personales ni sensibles en los artefactos de diff; las pruebas utilizan marcadores de posición neutros y específicos del proyecto.
• Los límites de nomenclatura y arquitectura siguen los contratos del proyecto (AGENTS.md, Descripción general de la arquitectura).

Revisión de la superficie de deriva

Trata las nuevas superficies interpretativas duplicadas como un riesgo de revisión. Un PR no debe añadir comentarios, ejemplos, instantáneas generadas, tablas de mapeo, réplicas de configuración ni registros paralelos que reformulen un comportamiento que ya pertenece al código, los esquemas, las pruebas, WIT, la configuración o el despacho en tiempo de ejecución, a menos que la nueva superficie se derive mecánicamente de ese propietario o apunte claramente de vuelta a él.

Bloquea o solicita cambios cuando la nueva superficie puede desviarse y futuros lectores, revisores o la automatización podrían tratarla como más autoritativa que la fuente. Ejemplos comunes incluyen comentarios que describen comportamientos no impuestos por el código, documentación que duplica manualmente una lista de enum o esquema, pruebas que capturan un detalle de implementación en lugar del comportamiento observable por el usuario, y registros que copian un espacio de claves ya perteneciente a otro módulo.

Prefiere una de estas resoluciones:

• Eliminar la superficie duplicada y hacer que el propietario canónico sea más fácil de leer.
• Genera la superficie secundaria a partir del propietario canónico.
• Sustituye la reformulación por una referencia a la fuente y el motivo por el que debe estar ahí.

Los comentarios why siguen siendo bienvenidos cuando capturan invariantes, riesgos o compensaciones no evidentes que el sistema de tipos y las pruebas no pueden expresar. Deben explicar la intención, no reformular el flujo de control cercano ni convertirse en un segundo contrato.

Despacho tipado para espacios de claves compartidas

Para espacios de claves compartidas como nombres de métodos wire, claves de tipos de canal compilados, slots de proveedores o claves de registro frontend/backend, aplica esta regla resolviendo cadenas brutas en el límite de la API o configuración. El código descendente debe despachar a través de un enum, tabla generada por macros, registro de traits/factories u otro propietario canónico. No agregues brazos match de cadenas paralelas, tablas de despacho escritas a mano ni listas duplicadas que deban mantenerse sincronizadas por memoria del revisor.

Esto no prohíbe las constantes de cadena en los límites de la API. Evita una segunda superficie de despacho donde agregar una nueva variante puede compilarse mientras se omite silenciosamente un consumidor. Buenos ejemplos son el registro Method de RPC para los nombres de métodos del protocolo y CHANNEL_COMPILE_SPECS para las claves de compilación de canales, donde un único propietario canónico impulsa la cobertura descendente.

Lista de verificación de revisión profunda (solo de alto riesgo)

Para los PR que lleven risk:high o domain:security, verifica un ejemplo concreto en cada categoría. Un caso concreto vale más que cinco afirmaciones genéricas.

• Límites de seguridad: se conserva el comportamiento predeterminado de denegación, sin ampliación accidental del alcance.
• Modos de fallo: manejo de errores explícito, se degrada de forma segura.
• Estabilidad del contrato: Compatibilidad de la CLI, configuración o API preservada o migración documentada.
• Forma del diff: los PR grandes o de nueva integración son coherentes, están justificados para fusionarse ahora, no se pueden dividir fácilmente y no son en su mayoría maquinaria duplicada.
• Artefactos generados: los archivos generados que afectan la política, el esquema, las rutas, las migraciones, los archivos de bloqueo, los artefactos de publicación, las capacidades, los paquetes, el comportamiento en tiempo de ejecución o las pruebas de revisión se revisan como código fuente.
• Compatibilidad de la toolchain: los cambios en MSRV o en una toolchain fijada son intencionales, están alineados en CI/Docker/superficies de instalación y están documentados para usuarios downstream/de compilación desde el código fuente.
• Observabilidad: fallos que se pueden diagnosticar sin filtrar secretos.
• Seguridad de la reversión: ruta de reversión y radio de explosión claros.

Forma del comentario

Preferir comentarios de estilo lista de verificación con un resultado explícito:

• Listo para fusionar (indica por qué).
• Requiere acción del autor (lista de bloqueadores ordenada).
• Requiere una revisión de seguridad o de tiempo de ejecución más profunda (indique el riesgo exacto y la evidencia solicitada).

Los comentarios vagos generan idas y vueltas innecesarias. Si te encuentras escribiendo “esto podría ser un problema”, invierte 30 segundos más y conviértelo en un escenario específico o elimina el comentario.

Clasificación de incidencias

El mismo principio de enrutamiento de riesgos se aplica a los problemas, pero las etiquetas y las señales son diferentes.

Las etiquetas risk:* de los issues describen el radio de impacto probable de la corrección según el reporte. Las etiquetas risk:* de los PR describen el diff real que se está revisando. Reevalúa el riesgo cuando un issue se convierta en un PR en lugar de trasladar automáticamente la etiqueta del issue.

Etiquetas de triaje

Assignee significa trabajo activo. La evidencia de enrutamiento registra por qué un issue necesita protección especial contra inactividad, tratamiento del tracker o una decisión diferida del maintainer. status:blocked solo necesita el bloqueador no resuelto registrado, a menos que también necesite protección status:no-stale por separado. El contrato del Project board define las fuentes de evidencia aceptadas y los resultados de enrutamiento. Las labels pueden identificar el área probable, pero las labels por sí solas no constituyen ownership ni protección contra inactividad.

Etiquetas de resolución

Use las etiquetas de resolución solo al cerrar o eliminar un elemento de la cola activa. Explican el resultado final; no reemplazan las etiquetas de ciclo de vida status:* en trabajo que debe permanecer abierto. La guía de etiquetas es la fuente de verdad para las definiciones actuales de etiquetas de resolución y las restricciones de migración.

Para los duplicados, enlaza el destino canónico antes de cerrar o redirigir la discusión. Para los informes no válidos, explica qué hace que el informe no sea accionable o a dónde debería dirigirse en su lugar. Para el trabajo que explícitamente decidimos no abordar, usa la ruta Won't Do a nivel de tablero / wontfix en vivo y deja una breve justificación.

Para PRs reemplazadas o rutas de issues, usa Superseding PRs y conserva la atribución de los colaboradores cuando sea relevante.

Si los registros o cargas útiles del informe contienen identificadores personales o datos sensibles, solicite su ofuscación antes de realizar una triaje más profunda. El proceso de triaje no debe propagar la exposición.

Administración de discusiones

Las discusiones son una superficie de comunidad mantenida solo cuando existe un responsable o una cadencia de revisión. La cadencia predeterminada es una revisión semanal por parte del mantenedor de los hilos nuevos y recientemente activos. Un responsable designado puede encargarse de esa revisión de la superficie, pero el responsable mantiene la superficie; no se convierte en el propietario de cada pregunta, idea o implementación que aparece allí.

Durante cada paso de Discussions:

1. Revisa los hilos nuevos y recientemente activos para verificar la adecuación a la categoría, preguntas y respuestas sin contestar, spam, datos sensibles y los hilos que hayan generado un resultado concreto para el proyecto.
2. Mantén las conversaciones ligeras de la comunidad en Discussions cuando aún sean exploratorias, se puedan responder ahí o resulten útiles como showcase, demo, encuesta, anuncio o hilo de feedback general.
3. Promueve los resultados concretos a la superficie de seguimiento correspondiente: los errores y los alcances de funcionalidades aceptados a issues, las propuestas de arquitectura a issues de RFC, los detalles específicos de PR a comentarios de PR, y las reglas operativas duraderas a la documentación para mantenedores o contribuidores.
4. Cierra el ciclo en la Discussion de origen con un breve resumen y un enlace al issue, RFC, PR o documento que ahora es responsable del resultado. Marca una respuesta solo cuando la categoría y el resultado lo hagan correcto.
5. Redirige los hilos sensibles a la seguridad a la ruta privada de vulnerabilidades en Security issues, gestiona los datos sensibles según Privacy y cierra los hilos que sean pura publicidad o no relevantes para el proyecto. Conserva las demos o integraciones útiles relacionadas con el proyecto como material destacado de la comunidad cuando no estén pidiendo a los mantenedores que hagan seguimiento de trabajo.

Si los Discussions no se revisan según la cadencia documentada, no los presentes como una vía de entrada obligatoria. Trátalos como un archivo pasivo hasta que se restablezca un responsable o una cadencia.

Poda del backlog de PR

Usa la instantánea de la cola de solo informes al seleccionar la siguiente pasada de revisión:

python3 scripts/github/pr_review_queue.py --queue all --older-than-days 7 --format table

El comando ofrece una vista bajo demanda del estado actual de GitHub, no una cola persistente ni una fuente de autoridad para las fusiones. Esta instantánea all ejecuta los carriles compartidos de forma independiente, por lo que una PR puede aparecer en más de un carril; añade --author LOGIN para incluir mine. Usa --queue near-ready para empezar por las PR encaminadas por mantenedores cuyo estado de búsqueda en GitHub sea satisfactorio; esto prioriza las candidatas que podrían estar más cerca de la fusión, sin afirmar que se puedan fusionar o que tengan aprobaciones suficientes. Usa --format json para inspección o informes posteriores y --format links para obtener enlaces de búsqueda de GitHub. La búsqueda de GitHub proporciona las listas de candidatos; el script solo lee las líneas de tiempo para calcular la antigüedad de la acción del autor y las revisiones únicamente para el enrutamiento de la cabecera actual a second-Core. Los detalles ausentes o ambiguos siguen siendo desconocidos. Confirma la posibilidad de fusión, las comprobaciones y la aplicabilidad de las aprobaciones durante la revisión propiamente dicha. Prioriza y revisa las PR padre con Depends on #... antes que las hijas; cuando una PR padre no se pueda revisar, pospone la revisión exhaustiva de la PR hija, a menos que una parte independiente y acotada se beneficie de una revisión temprana; después, actualiza y vuelve a validar la PR hija cuando la PR padre se fusione. Las PR apiladas siguen siendo un carril de informe independiente y no pasan a estar listas para revisión simplemente por ser antiguas.

Cuando la demanda de revisión supera la capacidad:

1. Mantén las PR de bugs y seguridad activas (size:XS o size:S) en la parte superior de la cola.
2. Pide que los PRs superpuestos se consoliden; cierra los más antiguos con una justificación de reemplazo o sustitución después de que el autor lo confirme. Consulta Superseding PRs para conocer las reglas de atribución.
3. Usa la rampa de obsolescencia de PR que aparece a continuación. La depuración del backlog de PR usa needs-author-action y stale-candidate; los barridos de obsolescencia de issues usan status:stale según la política canónica de obsolescencia de issues.

Cuando un mantenedor envía una revisión de solicitud de cambios y el siguiente paso corresponde al autor del PR, aplica needs-author-action en el mismo paquete de revisión/etiqueta. No la añadas cuando el cambio solicitado pueda ser corregido por un mantenedor y este pretenda enviar la limpieza, cuando otro mantenedor o propietario asuma el control de la rama, o cuando el bloqueo esté a la espera de una decisión de un mantenedor en lugar del trabajo del autor.

Si el error o la funcionalidad subyacente sigue siendo válido, consérvalo en un issue, una fila del tracker, un PR de reemplazo o un plan de relevo, en lugar de dar a entender que la idea fue rechazada. Exige un rebase y evidencia nueva de validación antes de reabrir cualquier cosa que haya sido cerrada por antigüedad.

Anulación de automatización

Utilice esto cuando la salida de la automatización genere efectos secundarios en la revisión:

1. Etiqueta de riesgo incorrecta: establece la etiqueta risk:* prevista. Si la automatización de riesgos futura está activa, sigue también el contrato de automatización de etiquetas para risk:manual; la anulación no omite la regla de aprobación risk:high OR domain:security.
2. Cierre automático incorrecto en el triaje de issues: reabrir, eliminar la etiqueta de enrutamiento, dejar un comentario aclaratorio.
3. Spam o ruido de etiquetas: conserve un comentario canónico del mantenedor, elimine las etiquetas de ruta redundantes.
4. Alcance ambiguo del PR: solicita una división antes de la revisión profunda; no intentes revisar dos asuntos a la vez.

Entrega

Al pasar la revisión a otro mantenedor o agente durante el proceso, incluye:

1. Resumen del alcance.
2. Clase de riesgo actual y justificación.
3. Lo que has validado.
4. Bloqueantes abiertos.
5. Acción siguiente sugerida.

Esto mantiene baja la pérdida de contexto y evita que el siguiente revisor vuelva a realizar las mismas consultas que ya hiciste.

Limpieza semanal de la cola

• Recorre la cola de elementos obsoletos (stale). Aplica status:no-stale solo según las reglas del contrato del tablero del proyecto: cuando un trabajo aceptado o de larga duración tenga una razón registrada para permanecer abierto, evidencia de enrutamiento visible para los colaboradores y ninguna otra exclusión de obsolescencia ya aplicable. Los rastreadores de versiones activas y los rastreadores de RFC o diseño activos pueden mantener la protección contra obsolescencia de forma predeterminada cuando el propio issue identifique con claridad la superficie activa de coordinación o decisión; revísalos cuando el milestone se cierre, cuando el rastreador se desvíe del estado actual, cuando el RFC alcance una decisión, sea reemplazado o se cierre, o cuando el issue deje de representar una superficie activa de decisión del proyecto. Hasta que se implemente la auditoría de exenciones de obsolescencia, trata los issues existentes con status:no-stale que carezcan de esos datos como hallazgos de auditoría en lugar de candidatos automáticos a obsolescencia.
• Prioriza primero los PR de errores y seguridad de size:XS o size:S.
• Convierte las preguntas recurrentes de soporte en mejoras de documentación y directrices para respuestas automáticas.

El objetivo es una cola donde cada PR abierto esté siendo revisado activamente, bloqueado por el autor o bloqueado por algo externo, y nunca simplemente esperando porque nadie llegó a revisarlo.