Flujo de trabajo de PR

El contrato de gobernanza desde el lado del mantenedor para las PRs dirigidas a master. Las configuraciones de protección de ramas, los contratos de preparación DoR/DoD y el protocolo de recuperación ante fallos se encuentran aquí. La revisión diaria se realiza en el Manual del Revisor. El flujo orientado al contribuidor se encuentra en Cómo contribuir.

Objetivos de gobernanza

El flujo de trabajo existe para mantener cinco cosas verdaderas bajo un alto volumen de PR:

1. El rendimiento de fusión es predecible.
2. La calidad de la señal de CI se mantiene alta, con retroalimentación rápida y pocos falsos positivos.
3. La revisión de seguridad es explícita en las superficies de riesgo.
4. Los cambios son fáciles de razonar y de revertir.
5. Los artefactos del repositorio se mantienen libres de datos personales o sensibles.

El bucle de control que lo entrega está diseñado en capas a propósito:

• Clasificación de entrada: las etiquetas de ruta/tamaño/riesgo dirigen el PR a la profundidad adecuada.
• Validación determinista: la puerta de merge depende de comprobaciones reproducibles, no de comentarios subjetivos.
• Profundidad de la revisión basada en el riesgo: las consecuencias de alto riesgo y los límites de seguridad reciben una revisión exhaustiva, mientras que el trabajo de bajo riesgo se mantiene ágil.
• Contrato de fusión con prioridad a la reversión: cada ruta de fusión incluye una historia de recuperación concreta.

La automatización gestiona las etiquetas de ruta/ámbito, los informes manuales de planificación del panel de incidencias y los controles de CI. Las etiquetas de riesgo, tamaño, tipo y nivel de contribuidor son decisiones de admisión de los mantenedores, salvo que un flujo de trabajo mantenido se encargue explícitamente de ellas. La responsabilidad final de la fusión sigue recayendo en los mantenedores humanos y los autores de las PR. Una PR que incluya risk:high o domain:security requiere una revisión exhaustiva y dos aprobaciones independientes del Core Team; la revisión automatizada no cuenta como una aprobación del Core Team.

Contrato del tablero de proyecto

El tablero del proyecto es un tablero de planificación automatizado, no la cola autorizada de revisión de PR.

Usa el panel para evaluar la preparación de incidencias, evidencias de enrutamiento, agrupación de hojas de ruta, dependencias, estado de bloqueos y motivos de exención por inactividad. Esas señales cambian con la lentitud suficiente como para que un campo del panel o un carril de planificación siga siendo útil.

La automatización actual es manual y solo genera informes. project-dashboard-plan.yml se ejecuta en workflow_dispatch para un único número de issue, lee la carga útil del issue y escribe un resumen del paso proponiendo el valor existente de Project Status que mejor coincide con las etiquetas en vivo y el estado del issue. No escribe campos del proyecto, no edita issues, no añade etiquetas, no publica comentarios ni se ejecuta automáticamente en eventos de issue.

Un resumen JSON de este desglose de planificación se encuentra en project-board-contract.json. Trátalo como el contrato para el planificador de solo informe y la futura automatización de actualización del tablero, no como aprobación para ejecuciones automáticas de eventos de incidencias ni para la mutación activa de GitHub Project todavía. Las escrituras en vivo de ProjectV2 necesitan una asignación de campos aprobada, una credencial o instalación de la app con ámbito de proyecto, y una lectura de retorno que compare el estado planificado con el estado en vivo de Project antes de que los mantenedores dependan de ello.

No reflejes el estado de revisión de PR nativo en los carriles del tablero manual. El estado de PR de GitHub controla la decisión de revisión, las comprobaciones requeridas, la posibilidad de fusión, los conflictos, las aprobaciones obsoletas y la disponibilidad para la fusión. Si el tablero muestra posteriormente un enrutamiento de PR derivado como DIRTY, BEHIND o APPROVED, considéralo una vista de panel del estado de GitHub, no una fuente de verdad independiente.

Esto mantiene el tablero útil sin pedir a los responsables que lo actualicen después de cada push, revisión o ejecución de CI.

El etiquetado automático del tamaño y del riesgo son cuestiones de flujo de trabajo independientes. #9345 puede volver a calcular las etiquetas de tamaño deterministas cuando se actualizan las PR. Su clasificador de riesgo seguirá limitado a informes hasta que los responsables de mantenimiento revisen las pruebas y habiliten por separado la modificación de etiquetas de riesgo. La automatización del riesgo debe respetar risk:manual hasta que un responsable de mantenimiento elimine esa anulación. El planificador del panel de incidencias no aplica ni recalcula las etiquetas de riesgo, tamaño o tipo de las PR.

Evidencia de enrutamiento de incidencias

El triaje de issues sigue siendo una responsabilidad compartida de los maintainers. Los issues aceptados no necesitan un mapa de owners permanente para poder seguir abiertos, y CODEOWNERS no hace que los code owners sean responsables de cada issue en un área coincidente.

Las issues necesitan evidencia de enrutamiento visible para los colaboradores cuando un estado especial las ocultaría de la revisión rutinaria o de las limpiezas de elementos obsoletos: status:no-stale, un estado activo de tracker de release/RFC/diseño, o una decisión diferida del maintainer. status:blocked mantiene su regla más simple: registra el bloqueador sin resolver y revisa la protección contra obsolescencia cuando el bloqueador se elimine.

Usa estos significados de forma consistente:

CODEOWNERS es un mecanismo de enrutamiento de revisiones de PR. Puede identificar a las personas que se deben consultar cuando un problema afecta claramente a una ruta, pero no crea la propiedad del problema ni debe replicarse en políticas obsoletas como un mapa de enrutamiento privado.

La evidencia de enrutamiento se refiere a la siguiente decisión, no a la propiedad de la entrega. Un problema enrutado no debería quedar en un limbo de “propiedad”; la siguiente actualización visible debería hacer explícito uno de estos resultados: asignar un implementador activo, dejar el problema listo para colaboradores, enrutarlo a un rastreador o hito, registrar el bloqueante, programar un punto de decisión concreto del mantenedor, o cerrarlo/aplazarlo con justificación.

Programar una incidencia para la clasificación por parte del mantenedor solo es válido cuando la incidencia registra qué decisión se necesita, dónde se hará el seguimiento de esa decisión y cuándo se revisará. Después de esa fase de clasificación, reemplaza el enrutamiento de clasificación por un implementador activo, un alcance listo para contribuidores, una ruta de seguimiento o hito, un estado bloqueado/aplazado o una justificación de cierre.

Para los issues protegidos, registra tanto el motivo de la exención de obsolescencia como la próxima instancia de decisión antes de añadir o mantener status:no-stale. Entre las fuentes de evidencia visibles útiles se incluyen:

• una persona asignada que esté realizando trabajo activo, además de una nota visible en el issue, una sección del cuerpo o una entrada en el rastreador que explique por qué no debe aplicarse el tratamiento de inactividad;
• un comentario de incidencia, una sección del cuerpo de la incidencia o un campo público de la incidencia que registre el motivo de exención por inactividad y la próxima instancia de decisión;
• un campo público del proyecto que es visible para los lectores normales de issues y se mantiene activamente;
• un seguimiento público enlazado, hito, RFC o incidencia de diseño que registre por qué la incidencia permanece abierta y cuándo debe revisarse.

Los rastreadores de versiones activas y los rastreadores activos de RFC o de diseño son superficies de coordinación duraderas. Cuando el título, el cuerpo, las etiquetas o el hito de la incidencia identifican claramente un rastreador o RFC activo, el rastreador mismo proporciona el motivo de exención por inactividad y la superficie de enrutamiento visible para los colaboradores; no necesita comentarios repetitivos por cada incidencia. Reconsidera la exención cuando el hito se cierre, el rastreador se desvíe del estado real de la versión, el RFC llegue a una decisión, sea reemplazado o se cierre, o cuando la incidencia ya no represente una superficie de decisión activa del proyecto.

Cuando se necesite una etiqueta de marcador de seguimiento, usa type:tracker. Se aplica a superficies de coordinación de padre solo de incidencias, como rastreadores de lanzamientos, rastreadores de hojas de ruta o epopeyas, rastreadores de RFC/diseño, rastreadores de lotes de implementación, rastreadores de limpieza y rastreadores de auditoría. No la apliques a incidencias hijas ordinarias, solicitudes de características ordinarias, errores, PR o elementos meramente enlazados desde un rastreador. type:tracker ayuda a las personas y a la automatización a encontrar la superficie padre; no reemplaza el motivo de exención por obsolescencia requerido, la siguiente superficie de decisión, el hito, el asignado ni los criterios de cierre. Si la etiqueta activa todavía no existe, no la sustituyas por roadmap, type:roadmap ni otro alias; crea y migra la etiqueta canónica mediante un paquete de etiquetas exacto independiente.

Si no existe ninguno de esos y el issue no es un tracker activo ni un RFC, el issue puede permanecer abierto mientras continúa el triage, pero no debe depender de status:no-stale como un escudo permanente. Hasta que se implemente la auditoría de exención de obsolescencia, la falta de evidencia de razón o enrutamiento es un hallazgo de auditoría y una corrección propuesta, no un desencadenante automático de cierre por obsolescencia.

Política de hitos con nombre

Los hitos con nombre son cohortes finitas de entrega para resultados acotados dentro de dominios de capacidades, no backlogs permanentes de dominio. Para esta política, un hito con nombre se organiza en torno a un resultado en lugar de una versión numerada; Parking Lot y Icebox son áreas de espera, no hitos con nombre. Asigne a cada nuevo hito el nombre Domain: Bounded Outcome. Prefiera RPC Client: Authentication & Authorization a un nombre amplio y reutilizable como Auth. Un título combinado ocupa cada dominio que nombra.

Trata cada hito con nombre abierto como activo. Antes de abrir otro, los mantenedores deben confirmar explícitamente que existe capacidad de coordinación y revisión para la cohorte adicional. Registra por qué la cohorte no puede esperar y qué hito actual se prevé que se cierre a continuación. Cuando se agote la capacidad, no abras otro hito con nombre hasta que se cierre uno o el trabajo propuesto se consolide en una cohorte existente. Reevalúa la capacidad cada vez que cambien sustancialmente la disponibilidad de los mantenedores o la carga de revisión.

Mantén como máximo un hito con nombre activo por dominio. Una excepción explícita del mantenedor puede permitir que resultados independientes del mismo dominio avancen en paralelo cuando la decisión documenta por qué se justifica el coste adicional de coordinación.

Cada hito con nombre necesita un alcance explícito y criterios de cierre, aunque la fecha de vencimiento es opcional. No dejes abierta una cohorte pausada: redirige su trabajo sin terminar y cierra el hito. Antes de cerrar cualquier hito con nombre, cierra o redirige todas las incidencias sin terminar y añade una nota de cierre que indique si el resultado se completó, se canceló o fue reemplazado. Los hitos con nombre cerrados deben permanecer cerrados. El trabajo posterior puede formar un nuevo hito con nombre solo cuando exista suficiente alcance coherente para definir otro resultado finito. Pon a ese hito el nombre del resultado; no crees sucesores continuos v2, v2.1 o similares de forma predeterminada.

GitHub permite que una incidencia o una solicitud de incorporación de cambios pertenezca a un único hito. El trabajo necesario para completar una cohorte con nombre permanece en ese hito con nombre hasta completarse, incluso cuando se incluye en una versión numerada. Registra la inclusión en la versión en el seguimiento de versiones y en el registro de cambios. Usa hitos de versión numerados para errores urgentes, mantenimiento y otro trabajo sujeto a una versión que quede fuera de una cohorte con nombre.

Una vez que un hito con nombre esté activo, limita la recepción de nuevos trabajos al trabajo necesario para completar la cohorte indicada: alcance directo, bloqueos, dependencias y regresiones. Dirige el resto del trabajo según su propósito:

Carriles de PR

Los lanes de PR son expectativas de enrutamiento, no otra familia de etiquetas obligatorias. Úsalos para decidir cuánta profundidad de revisión, secuenciación y atención del maintainer necesita un PR. CODEOWNERS, el estado nativo de revisión de GitHub, CI, las etiquetas, los issues vinculados y las palabras clave de relación explícitas siguen siendo los que portan los datos reales de enrutamiento.

No construyas un tablero de PR manual separado para estos carriles a menos que el estado nativo de GitHub y CODEOWNERS dejen de responder la pregunta de enrutamiento. Verifica el estado de merge nativo de GitHub antes de la revisión normal del carril: DIRTY significa resolver primero los conflictos; BEHIND por sí solo es mantenimiento de mergeabilidad, no un bloqueante de cara al autor.

Configuraciones requeridas del repositorio

Protección de ramas en master:

• Requerir comprobaciones de estado antes de fusionar.
• Requerir la comprobación de la CI Required Gate.
• Requerir revisiones de solicitudes de extracción antes de la fusión.
• Requerir revisión de CODEOWNERS para rutas protegidas. .github/** (incluyendo .github/workflows/**) pertenece a los mantenedores listados en .github/CODEOWNERS, por lo que los cambios en los flujos de trabajo necesitan la revisión de un mantenedor propietario.
• Mantenga la omisión de ramas / conjuntos de reglas limitada a los propietarios de la organización.
• Descartar aprobaciones obsoletas cuando se empujen nuevos commits.
• Restringir la fuerza de empuje.
• Todos los PRs de los colaboradores se dirigen directamente a master.

Definición de Listo (DoR)

Antes de solicitar la revisión, la PR tiene todas estas:

• Plantilla de PR completamente completada.
• Límite del alcance explícito (qué cambió / qué no cambió).
• Evidencia de validación adjunta, salida real del comando, no “CI lo verificará.”
• Campos de seguridad y privacidad, compatibilidad y (para rutas de riesgo) reversión completados.
• Reglas de privacidad e higiene de datos satisfechas, redacción de pruebas neutral y limitada al ámbito del proyecto. Consulte Privacidad.
• La redacción similar a la identidad, cuando sea inevitable, utiliza las etiquetas nativas de ZeroClaw / proyecto.

Definición de Hecho (DoD)

Antes de fusionar:

• CI Required Gate está en verde.
• Los revisores requeridos han aprobado (incluidas las rutas de CODEOWNERS); un PR que lleve risk:high o domain:security tiene dos aprobaciones independientes del Core Team.
• Las etiquetas de riesgo coinciden con el diff real y la consecuencia, en lugar de con la ubicación general del componente. Consulta Etiquetas.
• El impacto en la migración y la compatibilidad está documentado.
• La ruta de retroceso es concreta y rápida.

Lista de verificación para el mantenimiento de fusiones

Cada fusión:

• El alcance está bien definido y es comprensible.
• La puerta de CI está verde.
• Las comprobaciones de calidad de la documentación están verdes cuando se han modificado los documentos.
• Los campos de seguridad y privacidad están completos; la evidencia está redactada/anonimizada.
• Un PR que incluya risk:high o domain:security tiene dos aprobaciones independientes del Core Team; la revisión automatizada no cuenta.
• Las notas del flujo de trabajo del agente son suficientes para la reproducibilidad (si se utiliza asistencia de IA).
• El plan de reversión es explícito.
• El título del commit sigue Conventional Commits.

Squash-merge con el historial completo de commits preservado en el cuerpo. La skill squash-merge produce tanto la insignia morada Merged como el cuerpo con formato de conventional-commits; consulta Skills para conocer la invocación.

Política de contribución de IA / Agente

Se aceptan PRs asistidos por IA. La revisión también puede ser asistida por agentes.

Requerido:

1. Resumen del PR con límite de alcance.
2. Evidencia explícita de prueba / validación.
3. Notas sobre el impacto en la seguridad y la reversión para cambios riesgosos.

Recomendado:

1. Notas breves de la herramienta / flujo de trabajo cuando la automatización influyó materialmente en el cambio.
2. Fragmentos opcionales de la indicación / plan para la reproducibilidad.

No requerimos que los contribuyentes cuantifiquen la propiedad de líneas entre IA y humanos. El diff y la evidencia de validación asumen la carga.

Para PRs con alta carga de IA, los revisores se centran en:

• Compatibilidad de contratos.
• Límites de seguridad.
• Manejo de errores.
• Regresiones de rendimiento y memoria.
• Si el autor puede responder preguntas sobre el comportamiento y el alcance del impacto (comprensión de la intención).

Revisar el SLA y la disciplina de la cola

• Primer objetivo de triaje del mantenedor: dentro de 48 horas.
• Los PR bloqueados reciben un único comentario con una lista de tareas accionable, no una serie de revisiones parciales.
• status:no-stale está reservado para trabajo aceptado o de larga duración con un motivo de exención de obsolescencia registrado y evidencia de enrutamiento visible para los contribuyentes cuando el issue no esté ya protegido por otra exclusión de obsolescencia. Los rastreadores de versiones activos y los rastreadores de RFC o de diseño activos pueden usar el propio rastreador como ese motivo visible y superficie de enrutamiento mientras permanezcan activos. Las exenciones existentes que carezcan de esos datos son hallazgos de auditoría hasta que se incorpore el paquete de reparación de exención de obsolescencia.

Para el trabajo apilado, se requiere Depende de #... explícito para que el orden de revisión sea determinista.

Aplica operativamente ese orden determinista: prioriza y revisa un elemento padre antes que sus elementos secundarios; cuando un elemento padre no sea revisable, pospón la revisión exhaustiva de sus elementos secundarios, a menos que una parte independiente y acotada se beneficie de una revisión temprana; después de que se integre el elemento padre, actualiza y vuelve a validar el elemento secundario. Que un elemento padre pase a ser revisable no hace que las evidencias del elemento secundario recopiladas previamente estén actualizadas.

Para obtener una instantánea meramente informativa de las colas activas de GitHub, ejecuta python3 scripts/github/pr_review_queue.py --queue all --older-than-days 7 --format table. Los valores de --queue son near-ready, maintainer, second-core, author-action, stacked, mine y all; --format acepta table, json o links. near-ready restringe el carril maintainer a los PR cuyo estado en la búsqueda de GitHub sea correcto, para que los mantenedores puedan empezar con candidatos que quizá requieran menos trabajo antes de fusionarse; no establece que se puedan fusionar ni que las aprobaciones sean suficientes. all ejecuta los carriles compartidos de forma independiente, por lo que un PR puede aparecer en más de un carril; añade --author LOGIN para incluir el carril mine. La búsqueda de GitHub proporciona las listas de candidatos. Solo author-action lee los detalles de la línea de tiempo para estimar la antigüedad de las solicitudes sin respuesta, y solo second-core lee las revisiones para encontrar una aprobación de Core en el head actual. El comando nunca escribe el estado de las colas ni modifica GitHub, e informa de los detalles ausentes o ambiguos como desconocidos. Es una ayuda para seleccionar trabajo, no una prueba de que esté listo para fusionarse.

Para las sustituciones, se requiere Supersedes #.... Consulta PRs que superseden para las reglas de atribución y plantillas.

La gestión de la cola del lado del revisor, el orden de depuración del backlog, el manejo de elementos obsoletos, la higiene de etiquetas, está en Reviewer Playbook.

Reglas de seguridad y estabilidad

Revise estas rutas detenidamente, ya que suelen contener comportamientos relevantes para los límites:

• crates/zeroclaw-runtime/ (incluyendo src/security/)
• crates/zeroclaw-gateway/ (ingreso, autenticación, emparejamiento)
• crates/zeroclaw-tools/ (cualquier cosa con capacidad de ejecución)
• .github/workflows/ y la canalización de lanzamiento

La ubicación de la ruta por sí sola no selecciona risk:high. Clasifica el diff real y su consecuencia según Etiquetas → Etiquetas de riesgo. Un límite de confianza, de credenciales, de compatibilidad, de gobernanza, de autoridad de publicación o de seguridad transversal recibe una revisión exhaustiva cuando el PR incluye risk:high o domain:security.

Los límites de acceso al sistema de archivos y el comportamiento de red o autenticación dentro de estos crates merecen especial atención, incluso cuando el cambio es pequeño.

Mínimo para los PRs risk:high o domain:security: declaración de amenaza o riesgo, notas de mitigación, pasos de reversión y dos aprobaciones independientes del Core Team.

Recomendado para los PRs risk:high o domain:security: una prueba específica que demuestre el comportamiento en los límites, además de un escenario explícito de modo de fallo con la degradación esperada.

Para las contribuciones asistidas por agentes que atraviesan estos límites, los revisores también verifican que el autor pueda explicar el comportamiento en tiempo de ejecución y el radio de impacto, no solo pegar la salida de validación.

Recuperación de fallos

Si un PR fusionado causa regresiones:

1. Revert en master inmediatamente.
2. Abre un problema de seguimiento con análisis de la causa raíz.
3. Vuelve a introducir la corrección únicamente con pruebas de regresión que cubran el modo de fallo.

Prefiere la restauración rápida de la calidad del servicio a una solución perfecta pero retrasada.

Lo que esta página NO cubre

• Mecánica de revisión del día a día: consulte Guía del Revisor y Protocolo de Revisión de PR.
• Umbrales y definiciones de etiquetas: consulte Labels.
• Reglas de privacidad y PII: consulta Privacidad.
• Atribución y plantillas de reemplazo: consulta PRs de reemplazo.
• Inventario y triaje de flujos de trabajo de CI: consulte CI & Actions.
• Procedimiento de lanzamiento: consulta el Runbook de lanzamiento.