xz-dev/mantenimiento-fork-downstream

Mantenimiento de Fork Downstream

Resumen

El propósito de mantener un fork downstream no es dejar que se desvíe gradualmente del upstream y se convierta en un fork duro que evolucione de forma independiente. Es mantener continuamente un conjunto de parches que sigan siendo utilizables, construibles y testeables.

El downstream sigue al upstream mientras proporciona rápidamente a los usuarios código y artefactos que contengan estas características y correcciones cuando los PRs aún no se han fusionado, los mantenedores del upstream están ocupados o un parche es de nicho pero urgente. No es un archivo de parches estático, sino un canal de distribución donde los parches realmente se ejecutan y permanecen bajo validación.

Un resultado integrado utilizable también permite que más personas prueben libremente los PRs del upstream, los parches downstream y sus propios cambios. A medida que el upstream avanza, construir, probar y revisar continuamente los parches reduce el riesgo de que los PRs se deterioren después de quedarse atrás del upstream, expone los problemas antes y ayuda a que los cambios eventualmente fluyan hacia el upstream.

Objetivos Principales

• Evitar que el fork downstream se convierta en un fork duro que permanezca separado del upstream.
• Seguir continuamente al upstream en lugar de preservar solo una rama estática de un punto en el tiempo.
• Mantener cada parche de forma independiente construible, testeable, revisable y adecuado para su envío o mantenimiento continuo de PR.
• Proporcionar código y artefactos directamente utilizables a través de la rama principal o de lanzamiento.
• Permitir que los usuarios prueben PRs, parches y sus propios cambios contra un resultado integrado real.
• Detectar conflictos entre parches y el upstream temprano, mantener los PRs fusionables y ayudar a que los parches fluyan hacia el upstream.

Modelo de Ramas

El repositorio determina los nombres reales de las ramas. No asuma una rama predeterminada, un nombre de remoto o una plataforma de alojamiento.

Rama Principal del Upstream

La rama principal del upstream es el punto de partida para cada reconstrucción. Obtenga su último estado antes de sincronizar y use un commit específico del upstream como base para la compilación actual.

La rama principal o de lanzamiento del downstream no debe convertirse en la nueva base para los parches. Un parche siempre debe dejar claro qué cambia en relación con el upstream.

Ramas de Parches

Mantenga cada parche independiente en su propia rama y manténgalo bajo los estándares normales de PR:

• Mantenga el alcance enfocado y los commits y la explicación claros.
• Incluya suficientes pruebas para demostrar el comportamiento.
• Hágalo independientemente construible y revisable en el upstream actual.
• Declare solo las dependencias necesarias y evite vincularlo a otros parches downstream.
• Hágalo adecuado para su envío directo como PR al upstream o para el mantenimiento continuo de un PR existente.
• En general, una rama de parche no debe modificar archivos de lanzamiento mantenidos centralmente por los mantenedores del upstream, como CHANGELOG. Los cambios de documentación necesarios deben limitarse a comentarios de código, documentación de API y notas de implementación directamente relacionadas con ese parche. Mantenga la lista de parches downstream y las notas de lanzamiento de forma centralizada en la rama de mantenimiento.

La rama de parche es la fuente de verdad a largo plazo para ese parche. Un commit de integración en la rama de lanzamiento no es la única copia del parche y no debe contener correcciones temporales que solo existan en el historial de lanzamientos.

Ramas de Parches de Compatibilidad Temporal

Cuando varios parches se aplican de forma independiente pero producen un conflicto de compilación, prueba o comportamiento al combinarse que no pertenece a ninguna rama de PR individual, mantenga un parche de compatibilidad en una rama tmp/parche/<nombre>.

Dicha rama aborda solo el problema de compatibilidad downstream para una combinación de parches específica. No fuerce la corrección en una de las ramas de PR independientes y no permita que se convierta en una nueva rama de características a largo plazo. Debe indicar de qué parches depende, dónde pertenece en el orden, qué comportamiento combinado valida y cuándo se puede retirar.

En la orquestación de sincronización en la rama ci, agregue tmp/parche/<nombre> en orden inmediatamente después de los parches de los que depende. Si una fusión de Git anterior ya ha producido conflictos textuales no resueltos, una rama de compatibilidad posterior no puede cruzar ese conflicto. En ese caso, la orquestación de ci debe aplicar explícitamente el manejo de compatibilidad correspondiente en el paso donde ocurre el conflicto antes de continuar con la reconstrucción; simplemente agregar la rama al final de la lista no es suficiente.

La Rama de Mantenimiento ci

Cuando el fork necesita llevar automatización como GitHub Actions, mantenga una rama ci separada. Si el repositorio ya tiene una rama equivalente, conserve su nombre. Esta rama es la superposición de lanzamiento del fork downstream y es responsable de:

• CI/CD, empaquetado, lanzamientos y configuración del repositorio específicos del downstream.
• Obtener automáticamente el upstream, integrar los parches en orden, reconstruir la rama de lanzamiento y enviar de forma segura.
• Pruebas adicionales de parches individuales downstream y pruebas de integración de múltiples parches.
• El README downstream, la lista de parches, las notas de lanzamiento y cualquier instrucción de mantenimiento específica del downstream.
• El orden de integración fijo de los parches regulares habilitados y las ramas tmp/parche/<nombre>.

Si el usuario o el fork downstream tienen requisitos de mantenimiento más allá de este flujo de trabajo general, manténgalos en un archivo MAINTAIN.md propiedad del downstream en la rama ci. Debe indicar cómo se debe mantener este fork en particular y registrar cualquier regla especial que los futuros mantenedores y la automatización deban seguir. Trátelo como una guía específica del repositorio: léalo antes de cambiar las ramas de parches, la orquestación de sincronización o el historial de lanzamientos, y manténgalo actualizado cuando esos requisitos cambien.

Cuando las reglas de mantenimiento especiales podrían pasarse por alto, agregue un aviso conciso en el README.md de la rama ci que enlace a MAINTAIN.md. Mantenga las reglas detalladas en MAINTAIN.md en lugar de duplicarlas en el README.

La rama ci puede llevar centralmente la automatización de lanzamientos downstream, pero no mezcle parches de comportamiento del producto en ella. Los cambios en tiempo de ejecución deben permanecer en ramas adecuadas para la construcción, prueba y envío de PRs al upstream de forma independiente.

Esta habilidad incluye el archivo de GitHub Actions utilizado por la práctica actual: ref/upstream-sync.yml. Cuando se necesite sincronización automática de GitHub, cópielo como punto de partida para .github/workflows/upstream-sync.yml, luego adapte la dirección del upstream, la rama predeterminada/de lanzamiento, las listas de ci y parches, el orden de tmp/parche/<nombre>, el programa de sincronización, los archivos propiedad del downstream, los secretos y las comprobaciones para el repositorio de destino. El archivo conserva la configuración específica del proyecto de su proyecto original y no debe habilitarse sin revisión.

Al configurar schedule, primero pregunte al usuario durante qué horas cada día debe ejecutarse la sincronización. El cron de GitHub usa UTC de forma predeterminada a menos que el flujo de trabajo establezca explícitamente una timezone compatible. No programe trabajos en el minuto 0 de la hora: la documentación oficial de GitHub indica que la carga es alta al comienzo de cada hora, por lo que los trabajos programados pueden retrasarse o incluso eliminarse bajo carga suficientemente alta. Para evitar también las marcas de cinco minutos comunes, no use un múltiplo de 5, como 10, 15, 20, 30, 40 o 45. Elija aleatoriamente un minuto de 1 a 59 que no sea múltiplo de 5 y escríbalo como un valor fijo en el flujo de trabajo, por ejemplo, ejecutando python -c 'import secrets; print(secrets.choice([m for m in range(1, 60) if m % 5]))'. Aquí, "aleatorio" se aplica solo al generar la configuración; no haga que el flujo de trabajo espere una demora aleatoria dinámica en cada ejecución.

Rama Principal o de Lanzamiento

La rama principal o de lanzamiento comienza desde el upstream más reciente e integra la rama de mantenimiento y las ramas de parches requeridas en un orden fijo. Proporciona el código completo, las compilaciones, las pruebas y los artefactos de lanzamiento.

Esta rama representa solo el resultado integrado downstream actual. No es la fuente de mantenimiento a largo plazo para ningún parche. Un problema puede reproducirse y analizarse primero aquí, pero la corrección debe regresar a la rama de parche o de mantenimiento propietaria, después de lo cual se debe regenerar el resultado integrado.

En el historial de lanzamientos, cada parche debe aparecer como un commit de integración claro y contable, haciendo visible tanto el número de parches downstream como el número de commits que el fork está por detrás del upstream.

Flujo de Trabajo

1. Inspeccionar el Estado Actual

Antes de comenzar, lea las instrucciones de mantenimiento y contribución del propio repositorio, incluido el MAINTAIN.md downstream cuando esté presente y cualquier aviso en el README que apunte a él. Inspeccione el árbol de trabajo, los remotos, la rama actual, las relaciones con el upstream y el proceso de sincronización y lanzamiento existente. Preserve o evite cualquier trabajo de usuario no confirmado; no lo limpie ni lo sobrescriba sin permiso.

2. Verificar Issues y Pull Requests del Upstream Antes de Programar

Antes de implementar cualquier nueva solicitud o escribir código, busque en el rastreador de issues y pull requests del upstream discusiones o implementaciones relacionadas. Verifique issues abiertos y cerrados, y PRs abiertos, en borrador, cerrados y fusionados; busque no solo la redacción exacta de la solicitud, sino también los nombres de componentes relevantes, mensajes de error y sinónimos razonables. Siga los issues vinculados, revisiones, commits y PRs de reemplazo lo suficiente como para establecer el estado actual.

Use el resultado para elegir la siguiente acción:

• Si el upstream ya implementa el requisito, verifique la versión aplicable y el comportamiento antes de decidir si todavía se necesita algún cambio downstream.
• Si un issue o PR activo lo cubre, prefiera contribuir a, probar, actualizar o transportar temporalmente ese trabajo en lugar de crear un duplicado desinformado.
• Si un enfoque anterior fue rechazado, revertido o reemplazado, comprenda la razón declarada antes de proponer una nueva implementación.
• Registre los enlaces relevantes del upstream y la conclusión en el plan de trabajo, las notas del parche o la descripción del PR para que la decisión siga siendo revisable.

Cuando existan issues o PRs relacionados en el upstream, no proceda directamente a la implementación. Primero establezca su estado real, alcance, decisiones, inquietudes no resueltas, comentarios de revisión, estado de implementación y relación con la solicitud del usuario. Luego sintetice la información relevante del upstream para el usuario en lugar de reenviar una lista de enlaces en bruto. Explique claramente lo que se aprendió, cómo afecta las suposiciones y el plan actuales, y qué partes de la solicitud original siguen siendo necesarias.

Si esa investigación produce un nuevo hallazgo que podría cambiar el alcance, enfoque, prioridad, propiedad, estrategia de compatibilidad o necesidad del trabajo, pregunte explícitamente al usuario si se debe cambiar el plan. Pause la implementación hasta que el usuario confirme si se debe mantener o revisar el plan. No reinterpretes silenciosamente la solicitud basándose en la discusión del upstream.

No comience la implementación simplemente porque una búsqueda de términos exactos no devolvió resultados. Realice una búsqueda razonable primero; si no se encuentra ninguna discusión o implementación relevante, indique ese resultado y continúe.

3. Reproducir en el Resultado Integrado Completo

Primero reproduzca el problema en la rama principal o de lanzamiento actual para confirmar cómo ocurre en la combinación de parches que los usuarios realmente ejecutan.

Durante el análisis, distinga entre:

• Un problema en el propio upstream.
• Un problema en un parche independiente.
• Un problema de integración entre parches; si no pertenece a ningún PR individual, colóquelo en tmp/parche/<nombre>.
• Un problema en CI, empaquetado, sincronización o documentación downstream.

4. Localizar y Corregir la Rama Propietaria

Encuentre la rama de parche responsable del comportamiento y complete la corrección y las pruebas en esa rama. Si el problema se refiere a la compatibilidad entre múltiples parches, cree o actualice tmp/parche/<nombre>. Si se trata de automatización de lanzamientos u otro trabajo de mantenimiento downstream, modifique la rama ci.

No confirme una corrección de conflicto o corrección de producto solo en la rama principal o de lanzamiento. Se perdería en la próxima reconstrucción desde el upstream y evitaría que el parche se revise de forma independiente.

5. Mantener el Parche Independientemente Utilizable

Siguiendo las convenciones del repositorio, actualice el parche al upstream más reciente, resuelva los conflictos en la rama de parche y ejecute las compilaciones y pruebas requeridas por ese parche.

Confirme que no depende de cambios ocultos en la rama de lanzamiento y que aún puede explicarse, revisarse y enviarse como un PR por sí mismo. Si ya existe un PR upstream, actualícelo también y continúe manteniéndolo en respuesta a los comentarios del upstream.

6. Reconstruir la Rama Principal o de Lanzamiento

Obtenga el upstream más reciente nuevamente, cree una rama candidata limpia a partir de un commit específico del upstream, y luego integre la superposición de lanzamiento, los parches regulares y las ramas tmp/parche/<nombre> requeridas en el orden fijo declarado por la rama ci.

Cada parche regular y parche de compatibilidad temporal debe producir su propio commit de integración claro en el historial de lanzamientos. Un repositorio puede usar squash merge o el método equivalente establecido por el proyecto, pero el resultado debe ser fácil de revisar y contar.

7. Validar el Resultado Utilizable

Ejecute las comprobaciones requeridas del repositorio contra la versión candidata completa, cubriendo al menos:

• Pruebas enfocadas para cada parche en sí mismo.
• Comportamiento integrado después de combinar múltiples parches.
• Si CI, empaquetado y documentación downstream provienen de las ramas correctas.
• Si el código o los artefactos que los usuarios realmente obtienen corresponden al commit validado.

Actualice la rama principal o de lanzamiento remota solo después de que tanto el código candidato como los artefactos pasen toda la validación requerida.

Sincronización Automática

El propósito de la sincronización automática es regenerar periódicamente un resultado de lanzamiento downstream utilizable a partir de un nuevo commit del upstream, no acumular correcciones en una rama de lanzamiento antigua.

El proceso de sincronización debe:

1. Usar los controles de concurrencia aceptados del repositorio para evitar que dos procesos de sincronización o lanzamiento actualicen la misma rama a la vez.
2. Obtener el upstream más reciente, la rama ci, todos los parches regulares habilitados y todas las ramas tmp/parche/<nombre>.
3. Crear una rama candidata limpia a partir del commit del upstream seleccionado explícitamente para esa ejecución.
4. Integrar la superposición de lanzamiento downstream, los parches regulares y los parches de compatibilidad temporal en el orden fijo declarado por la rama ci.
5. Ejecutar comprobaciones contra la rama candidata.
6. Si todas las comprobaciones pasan, enviar la rama candidata a la rama principal o de lanzamiento remota.
7. Si alguna comprobación falla, notificar al mantenedor y detenerse sin enviar.

Archivo de Ejemplo de GitHub Actions

Consulte ref/upstream-sync.yml para un ejemplo de flujo de trabajo de sincronización automática. Este archivo es un punto de partida y debe adaptarse al repositorio de destino antes de habilitarse.