Fijar versiones de plugins y temas para instalaciones antiguas de Discourse (ramas d-compat)

[Discourse]

Antecedentes

Los desarrolladores de temas y complementos generalmente buscan apuntar a la versión latest de Discourse, sin preocuparse por la compatibilidad hacia atrás. Sin embargo, los sitios que ejecutan versiones más antiguas de Discourse aún necesitan una versión del tema o complemento que funcione para ellos.

Para cerrar esa brecha, se puede indicar a Discourse que verifique una versión “anclada” (pinned) más antigua del tema o complemento. Existen dos mecanismos para esto, que se verifican en el siguiente orden:

1. Ramas git d-compat/<YYYY>.<M> en el repositorio del tema o complemento (el método principal: recomendado para todos los anclajes nuevos).
2. Un archivo YAML .discourse-compatibility en la raíz del repositorio (el mecanismo original, aún compatible como alternativa).

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 complemento o tema desde git, le 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 verifica la punta de esa rama en lugar de main.

La búsqueda solo se ejecuta cuando la verificación local está en la rama predeterminada del repositorio. Si has anclado intencionalmente a una rama diferente, la lógica de d-compat se omite y se respeta tu anclaje.

Para compatibilizar una versión más antigua de Discourse con este sistema:

1. Crea una rama llamada d-compat/<YYYY>.<M> a partir de un commit que se sepa que funciona en esa versión (por ejemplo, git checkout -b d-compat/2025.5 <commit>).
2. Súbelo a origin. Es posible que quieras proteger la rama de eliminaciones accidentales.
3. Incorpora cualquier commit de retrocompatibilidad en esa rama. Las instancias de Discourse en 2025.5.x los recogerán automáticamente en la siguiente actualización; las instancias en versiones más recientes 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 manualmente. Los esqueletos predeterminados de temas y complementos incluyen un flujo de trabajo d-compat-branch.yml que se ejecuta diariamente, verifica nuevas versiones del núcleo de Discourse y crea las ramas d-compat/<YYYY>.<M> correspondientes según sea necesario.

Si tu repositorio se creó a partir de una copia más antigua de los esqueletos, simplemente copia el archivo d-compat-branch.yml en tu directorio .github/workflows para que funcione.

Retrocompatibilizar una corrección en 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 más antigua de Discourse:

1. Crea una rama desde la rama d-compat objetivo y aplica la corrección mediante cherry-pick:

   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
   

2. Abre una PR con d-compat/2025.5 como rama base (no main). Pídele revisión y métrala de la misma manera que harías con cualquier otra PR.

3. Repite el proceso para cada rama d-compat/<YYYY>.<M> más antigua que necesite la corrección.

Los sitios en 2025.5.x recogerán el commit fusionado en su próxima actualización.

Alternativa heredada: el archivo `.discourse-compatibility`

Si no existe ninguna 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 complemento o tema:

< 3.2.0.beta2-dev: abcde

Discourse selecciona la entrada más baja que coincida con la versión del núcleo en ejecución, por lo que cualquier persona en < 3.2.0.beta2-dev verificará el commit abcde. Usa < (o el legado <=, el predeterminado cuando no se especifica ningún operador) para especificar el límite de versión. Recúrrelo solo si el sistema basado en ramas no puede expresar lo que necesitas.

---

Este documento está bajo control de versiones: sugiere cambios en GitHub.

[NateDhaliwal]

Si la versión es < 3.5.0.beta8-dev, ¿incluiría 3.5.0?

[david (David Taylor)]

El número 3.5.0 se considera “superior” a la versión preliminar “3.5.0.beta8-dev”.

Siempre puedes probar comparaciones en una consola de Ruby:

> Gem::Version.new("3.5.0") < Gem::Version.new("3.5.0.beta8-dev")
=> false

[NateDhaliwal]

Entendido. ¡Gracias por la explicación!

[david (David Taylor)]

Este documento ha sido actualizado para describir la nueva estrategia d-compat/* de RFC: A new versioning strategy for Discourse, la cual ya está disponible para su uso.