shagghiesuperstar/hermes-skills

Fusión por Lotes de PRs Solo de Documentación

Resumen

Muchas solicitudes de extracción (pull requests) pequeñas de documentación son más fáciles de revisar como una sola. Este procedimiento copia los archivos de varias solicitudes de extracción revisadas (solo de documentación) en un nuevo pull request borrador, con un commit por cada PR de origen. Los contenidos de los archivos se copian exactamente, sin ediciones. Las solicitudes de extracción de origen no se modifican. Luego, un revisor fusiona el PR por lotes y los PR de origen se cierran por su propio estado, no por ninguna acción en este procedimiento.

Cuándo Usarlo

• Varias solicitudes de extracción de documentación abiertas han superado la revisión y cada una afecta solo rutas de documentación.
• Un revisor solicita un solo pull request que las agrupe todas.

No utilizar para código, configuración, ni para ninguna solicitud de extracción de origen que no haya superado la revisión.

Características

• Un worktree temporal, por lo que el checkout de trabajo no se ve afectado.
• Una instantánea en vivo del estado de cada solicitud de extracción de origen: base, head y lista de archivos, verificada contra el commit head descargado.
• Reglas de omisión para pull requests cerrados, que tocan rutas fuera de la carpeta de documentación, colisionan con main o colisionan con otro pull request abierto.
• Un commit por cada PR de origen incorporado, con aserciones que detienen la ejecución si hay un PR de origen defectuoso.
• Validaciones de las rutas modificadas antes del push y un bloque de verificación que compara cada archivo con su head de origen.

Beneficios

• Un PR de origen defectuoso detiene la ejecución en lugar de incorporarse parcialmente.
• Se demuestra que el contenido de cada archivo incorporado es idéntico al de su origen.
• Los pull requests omitidos se enumeran con el motivo, por lo que nada se descarta en silencio.
• El pull request por lotes se abre como borrador, por lo que el revisor toma la decisión final.

Procedimiento

1. Trabajar en un worktree temporal. Obtener la rama main y los heads de los PR de origen, luego crear una nueva rama desde main en una carpeta temporal:

   git fetch origin main '+refs/pull/*/head:refs/remotes/origin/pr/*'
   git worktree add -b <batch-branch> <scratch-dir>/wt origin/main
   

   Si un fetch o push HTTPS falla por autenticación, ejecutar ese comando con el helper de credenciales establecido en la CLI del host de código, por ejemplo -c credential.helper= -c 'credential.helper=!gh auth git-credential'. No cambiar la configuración almacenada ni imprimir un token.

2. Tomar una instantánea del estado en vivo una vez. Para cada solicitud de extracción de origen, leer su estado, indicador de borrador, rama base, commit head y lista de archivos. También listar los pull requests abiertos para verificaciones de colisión. Asegurar que el commit head de cada origen coincida con el commit descargado refs/remotes/origin/pr/<n>.

3. Decidir omitir o incorporar, en orden numérico. Omitir un pull request (y registrar el motivo) si se cumple alguna de estas condiciones:

   • No está abierto.
   • Alguna de sus rutas está fuera de la carpeta de documentación.
   • Alguna de sus rutas ya existe en main. Para una ruta que ya está en main, comparar los blobs. Contenido idéntico significa que se incorporó antes; contenido diferente significa que necesita un rebase.
   • Otro pull request abierto modifica alguna de sus rutas.

4. Incorporar cada pull request como un commit. Para cada PR incorporado, hacer checkout de sus archivos desde su commit head y realizar un commit con un mensaje que nombre el PR. Ejecutar esto en un bucle que asegure que el PR está abierto, el head coincide, las rutas están bajo la carpeta de documentación y ninguna de ellas está en main. Una aserción fallida detiene la ejecución.

   git checkout <head-commit> -- <paths>
   git commit -m "docs: land #<n>"
   

5. Validar los cambios antes del push. La cantidad de archivos modificados fuera de la carpeta de documentación debe ser cero. El número total de archivos modificados debe ser igual a la suma de las cantidades de rutas por PR.

6. Construir el bloque de verificación. Para cada PR y cada una de sus rutas, comparar el blob en HEAD de la rama por lotes con el blob en el head de origen. Imprimir una línea por PR que muestre su head, su cantidad de rutas, su cantidad de blobs y COINCIDE, más un total. Pegar el bloque textualmente en la descripción del pull request por lotes.

7. Abrir el pull request por lotes como borrador. Subir la rama, luego crear el borrador contra main. El título indica la cantidad de PR realmente incorporados, no la cantidad considerada:

   gh pr create --draft --base main --title "docs: land <k> reviewed docs PRs" --body-file <body-file>
   

8. Escribir la descripción. Incluir una nota de que la compilación se omitió para un diff solo de documentación, la lista de PR incorporados con sus cantidades de archivos y heads, los PR omitidos con sus motivos, cualquier indicación para el revisor y el bloque de verificación. Volver a leer el estado del nuevo pull request y confirmar que es un borrador contra main.

Errores Comunes

• Ignorar la regla del borrador. Las instrucciones de una ejecución pueden solicitar un pull request listo para revisión. Abrirlo como borrador a menos que las reglas de la ejecución digan lo contrario, e indicarlo en la descripción.
• Un PR de origen basado en otra rama. Sus archivos pasan todas las reglas de ruta, pero incorporarlos a main cambia lo que significa el PR. Incluirlo solo si las reglas lo permiten, y marcarlo con el commit exacto a descartar.
• Sin base de fusión. Una búsqueda de base de fusión puede fallar para ese PR, y un diff contra la base daría error. Usar la lista de archivos en vivo como fuente de rutas. Verificar adicionalmente con un diff contra la base de fusión solo cuando exista.
• Incorporación parcial. Un PR que modifica archivos que main ya tiene puede ser omitido aunque sus otros archivos sean nuevos. No incorporarlo parcialmente.
• Inundar la salida con errores de ruta faltante. Una verificación de que una ruta existe en main imprime un error por cada ruta faltante. Redirigir el error estándar a /dev/null en esas comprobaciones.
• Rellenar el informe final. Reportar la lista de omitidos con motivos, las indicaciones y los totales de verificación. No enumerar cada archivo.
• Falta de gráfico o índice. Si un índice de inteligencia de código no está disponible para el repositorio, indicarlo en el informe y no omitir las reglas de ruta.

Verificación

• El pull request por lotes es un borrador contra main.
• Cada archivo incorporado tiene un blob que coincide con su head de origen, como se muestra en el bloque de verificación.
• Ningún archivo modificado está fuera de la carpeta de documentación.
• Cada pull request omitido tiene un motivo en la descripción.
• Los pull requests de origen no se modifican. Este procedimiento no los fusionó, aprobó, cerró ni comentó.