Contexto
Desenvolvedores de temas e plugins geralmente desejam direcionar o latest (mais recente) release do Discourse, sem se preocupar com compatibilidade reversa. No entanto, sites que executam releases mais antigos do Discourse ainda precisam de uma versão do tema/plugin que funcione para eles.
Para preencher essa lacuna, o Discourse pode ser configurado para verificar uma versão ‘fixada’ (pinned) mais antiga do tema/plugin. Existem dois mecanismos para isso, verificados em ordem:
- Ramais git
d-compat/<YYYY>.<M>no repositório do tema/plugin (o método primário — recomendado para todos os novos pins). - Um arquivo YAML
.discourse-compatibilityna 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>
Os releases do Discourse usam 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> correspondente à minha versão?” (por exemplo, d-compat/2025.5 para o Discourse 2025.5.x). Se houver, o Discourse faz o checkout da ponta (tip) desse ramo em vez do main.
A busca só é executada quando o checkout local está no ramo padrão do repositório. Se você fixou intencionalmente para um ramo diferente, a lógica d-compat é ignorada e sua fixação é respeitada.
Para suportar uma versão mais antiga do Discourse com este sistema:
- Crie um ramo chamado
d-compat/<YYYY>.<M>a partir de um commit que é conhecido por funcionar naquela versão (por exemplo,git checkout -b d-compat/2025.5 <commit>). - Faça o push para a
origin. Você pode querer proteger o ramo contra exclusão acidental. - Aplique (land) quaisquer commits de backport nesse ramo. Instâncias do Discourse em
2025.5.xos coletarão automaticamente na próxima atualização; instâncias em versões mais novas do Discourse continuarão seguindo o ramo padrão.
Você não precisa tocar no .discourse-compatibility de forma alguma ao usar ramos.
Criação automatizada de ramos (create-d-compat-branch.yml)
Na prática, raramente você precisa criar esses ramos manualmente. Os modelos (skeletons) padrão de temas e plugins incluem um workflow d-compat-branch.yml que é executado diariamente, verifica novas versões do núcleo do Discourse e faz o push de ramos d-compat/<YYYY>.<M> correspondentes conforme necessário.
Se o seu repositório foi criado a partir de uma cópia mais antiga dos modelos, basta copiar o arquivo d-compat-branch.yml para o diretório .github/workflows para que ele funcione.
Fazendo o backport de uma correção para um ramo d-compat
Quando você aplica (land) uma correção no ramo padrão que também precisa alcançar sites em um release mais antigo do Discourse:
-
Crie um ramo a partir do ramo d-compat de destino 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 -
Abra um PR com
d-compat/2025.5como ramo base (nãomain). Obtenha a revisão e faça o merge da mesma forma que faria com qualquer outro PR. -
Repita para cada ramo
d-compat/<YYYY>.<M>mais antigo que precise da correção.
Sites em 2025.5.x coletarã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 escolhe a entrada mais baixa que corresponde à versão do núcleo em execução, portanto, qualquer pessoa em < 3.2.0.beta2-dev fará o checkout do 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 é controlado por versão - sugira alterações no github.