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