Antecedentes
Los desarrolladores de temas y plugins generalmente desean dirigirse a la versión latest de Discourse, sin preocuparse por la compatibilidad hacia atrás. Sin embargo, los sitios que ejecutan versiones anteriores de Discourse aún necesitan una versión del tema/plugin que funcione para ellos.
Para cerrar esa brecha, se puede indicar a Discourse que descargue una versión anterior «fijada» (pinned) del tema/plugin. Existen dos mecanismos para esto, que se verifican en orden:
- Ramas git
d-compat/<YYYY>.<M>en el repositorio del tema/plugin (el método principal, recomendado para todas las nuevas fijaciones). - Un archivo YAML
.discourse-compatibilityen la raíz del repositorio (el mecanismo original, aún soportado como respaldo).
Si ambos existen, la rama tiene prioridad.
El sistema de ramas d-compat/<YYYY>.<M>
Las versiones de Discourse utilizan versiones basadas en fechas, como 2025.5, 2025.6, etc. Cuando Discourse actualiza un plugin o tema desde git, pregunta al repositorio: «¿Tienes una rama llamada d-compat/<YYYY>.<M> que coincida con mi versión?» (por ejemplo, d-compat/2025.5 para Discourse 2025.5.x). Si es así, Discourse descarga la punta de esa rama en lugar de main.
La búsqueda solo se ejecuta cuando la copia local está en la rama predeterminada del repositorio. Si has fijado intencionalmente a otra rama, la lógica de d-compat se omite y se respeta tu fijación.
Para admitir una versión anterior de Discourse con este sistema:
- Crea una rama llamada
d-compat/<YYYY>.<M>desde un commit que se sepa que funciona en esa versión (por ejemplo,git checkout -b d-compat/2025.5 <commit>). - Empújala a
origin. Puede que desees proteger la rama de la eliminación accidental. - Incorpora cualquier commit de retroceso (backport) en esa rama. Las instancias de Discourse en
2025.5.xlos recogerán automáticamente en la próxima actualización; las instancias en versiones más nuevas de Discourse seguirán rastreando la rama predeterminada.
No necesitas tocar .discourse-compatibility en absoluto al usar ramas.
Creación automatizada de ramas (create-d-compat-branch.yml)
En la práctica, rara vez necesitas crear estas ramas a mano. Las plantillas predeterminadas de temas y plugins incluyen un flujo de trabajo d-compat-branch.yml que se ejecuta a diario, verifica nuevas versiones del núcleo de Discourse y empuja las ramas d-compat/<YYYY>.<M> correspondientes según sea necesario.
Si tu repositorio se creó a partir de una copia anterior de las plantillas, simplemente copia el archivo d-compat-branch.yml en tu directorio .github/workflows para que funcione.
Retroceso (backport) de una corrección a una rama d-compat
Cuando has incorporado una corrección en la rama predeterminada que también necesita llegar a sitios con una versión anterior de Discourse:
-
Crea una rama a partir de la rama d-compat de destino y realiza un cherry-pick de la corrección:
git fetch origin git checkout -b backport/my-fix-2025.5 origin/d-compat/2025.5 git cherry-pick <commit-sha> git push -u origin backport/my-fix-2025.5 -
Abre una PR con
d-compat/2025.5como rama base (nomain). Obtén su revisión y fusión de la misma manera que cualquier otra PR. -
Repite el proceso para cada rama anterior
d-compat/<YYYY>.<M>que necesite la corrección.
Los sitios en 2025.5.x recogerán el commit fusionado en su próxima actualización.
Respaldo heredado: el archivo `.discourse-compatibility`
Si no existe una rama d-compat coincidente, Discourse recurre a un archivo YAML .discourse-compatibility en la raíz del repositorio, que mapea las versiones de Discourse a referencias git de tu plugin/tema:
< 3.2.0.beta2-dev: abcde
Discourse elige la entrada más baja que coincida con la versión del núcleo en ejecución, por lo que cualquiera que esté en < 3.2.0.beta2-dev descargará el commit abcde. Usa < (o el heredado <=, el valor predeterminado cuando no se especifica un operador) para especificar el límite de versión. Recurre a esto solo si el sistema basado en ramas no puede expresar lo que necesitas.
Este documento está controlado por versiones - sugiere cambios en github.