Fixando versões de plugins e temas para instalações mais antigas do Discourse (ramificações d-compat)

[Discourse]

Contexto

Desenvolvedores de temas e plugins geralmente desejam mirar na versão latest do Discourse, sem se preocupar com compatibilidade retroativa. No entanto, sites que executam versões mais antigas do Discourse ainda precisam de uma versão do tema/plugin que funcione para eles.

Para preencher essa lacuna, é possível instruir o Discourse a verificar uma versão “fixada” (pinned) mais antiga do tema/plugin. Existem dois mecanismos para isso, verificados na seguinte ordem:

1. Ramos git d-compat/<YYYY>.<M> no repositório do tema/plugin (o método principal — recomendado para todas as novas fixações).
2. Um arquivo YAML .discourse-compatibility na raiz do repositório (o mecanismo original, ainda suportado como fallback).

Se ambos existirem, o ramo tem prioridade.

O sistema de ramos d-compat/<YYYY>.<M>

As versões do Discourse utilizam versões baseadas em datas, como 2025.5, 2025.6, etc. Quando o Discourse atualiza um plugin ou tema a partir do git, ele pergunta ao repositório: „você tem um ramo chamado d-compat/<YYYY>.<M> que corresponda à minha versão?“ (por exemplo, d-compat/2025.5 para o Discourse 2025.5.x). Se sim, o Discourse verifica o topo desse ramo em vez do main.

A consulta ocorre apenas quando a instalação local está no ramo padrão do repositório. Se você fixou intencionalmente em um ramo diferente, a lógica do d-compat é ignorada e sua fixação é respeitada.

Para dar suporte a uma versão mais antiga do Discourse com este sistema:

1. Crie um ramo chamado d-compat/<YYYY>.<M> a partir de um commit conhecido por funcionar nessa versão (por exemplo, git checkout -b d-compat/2025.5 <commit>).
2. Faça o push para o origin. Você pode querer proteger o ramo contra exclusão acidental.
3. Aplique quaisquer commits de backport nesse ramo. Instâncias do Discourse na versão 2025.5.x receberão essas alterações automaticamente na próxima atualização; instâncias em versões mais recentes do Discourse continuarão rastreando o ramo padrão.

Você não precisa tocar no arquivo .discourse-compatibility ao utilizar ramos.

Criação automatizada de ramos (create-d-compat-branch.yml)

Na prática, raramente é necessário criar esses ramos manualmente. Os esqueletos padrão de temas e plugins incluem um fluxo de trabalho d-compat-branch.yml que é executado diariamente, verifica novas versões do núcleo do Discourse e faz o push dos ramos d-compat/<YYYY>.<M> correspondentes, conforme necessário.

Se seu repositório foi criado a partir de uma cópia mais antiga dos esqueletos, basta copiar o arquivo d-compat-branch.yml para o diretório .github/workflows para que ele funcione.

Backport de uma correção para um ramo d-compat

Quando você aplicar uma correção no ramo padrão que também precisa chegar a sites em uma versão mais antiga do Discourse:

1. Crie um ramo a partir do ramo d-compat alvo e faça o cherry-pick da correção:

   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. Abra um PR com d-compat/2025.5 como ramo base (não main). Faça a revisão e o merge da mesma forma que faria com qualquer outro PR.

3. Repita o processo para cada ramo d-compat/<YYYY>.<M> mais antigo que precise da correção.

Sites na versão 2025.5.x receberão o commit mesclado na próxima atualização.

Fallback legado: o arquivo `.discourse-compatibility`

Se nenhum ramo d-compat correspondente existir, o Discourse recorre a um arquivo YAML .discourse-compatibility na raiz do repositório, mapeando versões do Discourse para refs git do seu plugin/tema:

< 3.2.0.beta2-dev: abcde

O Discourse seleciona a entrada mais baixa que corresponda à versão do núcleo em execução, então qualquer pessoa em < 3.2.0.beta2-dev verificará o commit abcde. Use < (ou o legado <=, o padrão quando nenhum operador é fornecido) para especificar o limite da versão. Recorra a isso apenas se o sistema baseado em ramos não puder expressar o que você precisa.

---

Este documento está sob controle de versão — sugira alterações no GitHub.

[NateDhaliwal]

Se a versão for \u003c 3.5.0.beta8-dev, ela incluiria 3.5.0?

[david (David Taylor)]

N. 3.5.0 é considerado “maior” que a versão pré-lançamento “3.5.0.beta8-dev”.

Você sempre pode tentar comparações em um console ruby:

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

[NateDhaliwal]

Entendido. Obrigado pela explicação!

[david (David Taylor)]

Este documento foi atualizado para descrever a nova estratégia d-compat/* de RFC: A new versioning strategy for Discourse, que já está disponível para uso.