Контекст
Разработчики тем и плагинов, как правило, хотят ориентироваться на latest-релиз Discourse, не беспокоясь о обратной совместимости. Однако сайтам, работающим на более старых версиях Discourse, по-прежнему нужна версия темы/плагина, которая будет для них работать.
Чтобы преодолеть этот разрыв, Discourse можно указать, чтобы он проверял более старую «закреплённую» (pinned) версию темы/плагина. Для этого существуют два механизма, которые проверяются в следующем порядке:
- Git-ветки
d-compat/<YYYY>.<M>в репозитории темы/плагина (основной метод — рекомендуется для всех новых закреплений). - YAML-файл
.discourse-compatibilityв корне репозитория (изначальный механизм, по-прежнему поддерживается как запасной вариант).
Если оба варианта существуют, приоритет отдаётся ветке.
Система веток d-compat/<YYYY>.<M>
Релизы Discourse используют версии на основе даты, такие как 2025.5, 2025.6 и т. д. Когда Discourse обновляет плагин или тему из git, он обращается к репозиторию с вопросом: «Есть ли у вас ветка с именем d-compat/<YYYY>.<M>, соответствующая моей версии?» (например, d-compat/2025.5 для Discourse 2025.5.x). Если такая ветка есть, Discourse выполняет checkout её последней коммиты, а не ветки main.
Поиск выполняется только в том случае, если локальный checkout находится на ветке по умолчанию репозитория. Если вы намеренно закрепили другую ветку, логика d-compat пропускается, и ваше закрепление учитывается.
Чтобы поддержать более старую версию Discourse с помощью этой системы:
- Создайте ветку с именем
d-compat/<YYYY>.<M>из коммита, который, как известно, работает с этой версией (например,git checkout -b d-compat/2025.5 <commit>). - Отправьте её на
origin. Возможно, вы захотите защитить ветку от случайного удаления. - Внесите любые коммиты для обратной портировки (backport) в эту ветку. Экземпляры Discourse на
2025.5.xавтоматически подхватят их при следующем обновлении; экземпляры на более новых версиях Discourse продолжат отслеживать ветку по умолчанию.
При использовании веток вам вообще не нужно трогать .discourse-compatibility.
Автоматическое создание веток (create-d-compat-branch.yml)
На практике вам редко приходится создавать эти ветки вручную. В стандартных шаблонах тем и плагинов есть workflow d-compat-branch.yml, который запускается ежедневно, проверяет наличие новых версий ядра Discourse и при необходимости отправляет соответствующие ветки d-compat/<YYYY>.<M>.
Если ваш репозиторий был создан из более старой копии шаблонов, просто скопируйте файл d-compat-branch.yml в ваш каталог .github/workflows, чтобы запустить его работу.
Обратная портировка исправления в ветку d-compat
Когда вы внесли исправление в ветку по умолчанию, которое также должно быть доступно сайтам на более старых релизах Discourse:
-
Создайте ветку от целевой ветки d-compat и выполните 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 -
Откройте PR, указав
d-compat/2025.5как базовую ветку (а неmain). Получите ревью и объедините его так же, как любой другой PR. -
Повторите для каждой более старой ветки
d-compat/<YYYY>.<M>, которой требуется это исправление.
Сайты на 2025.5.x подхватят объединённый коммит при следующем обновлении.
Устаревший запасной вариант: файл `.discourse-compatibility`
Если соответствующая ветка d-compat не существует, Discourse обращается к YAML-файлу .discourse-compatibility в корне репозитория, который сопоставляет версии Discourse с git-ссылками (refs) вашего плагина/темы:
< 3.2.0.beta2-dev: abcde
Discourse выбирает самую нижнюю запись, соответствующую текущей версии ядра, поэтому все, кто находится на версии < 3.2.0.beta2-dev, выполняют checkout коммита abcde. Используйте < (или устаревший <=, который является значением по умолчанию, если оператор не указан), чтобы указать границу версии. Обращайтесь к этому механизму только в том случае, если система на основе веток не позволяет выразить то, что вам нужно.
Этот документ находится под контролем версий — предложите изменения на github.