Фиксация версий плагинов и тем для старых установок Discourse (.discourse-compatibility)

[Discourse]

Предыстория

Иногда темы или плагины требуют изменений, совместимых только с последней версией Discourse. В такой ситуации более старые версии Discourse можно настроить на использование более старой «закреплённой» версии плагина.

Это реализуется с помощью файла .discourse-compatibility в корневой директории репозитория темы или плагина. Это YAML-файл, где ключи указывают версию ядра Discourse, а значения соответствуют соответствующей версии вашей темы или плагина.

Версии ядра Discourse можно указывать с использованием операторов <= и <. По историческим причинам оператор <= используется по умолчанию, но в целом логичнее использовать <.

Закрепление версии темы/плагина

Например, если в ядре Discourse во время версии 3.2.0.beta2-dev (указанной в файле version.rb) были внесены изменения, от которых зависит ваш плагин или тема, то в файл .discourse-compatibility следует добавить запись следующего вида:

< 3.2.0.beta2-dev: abcde

где abcde — это ссылка на «устаревший» хэш коммита ВАШЕГО ПЛАГИНА, который должен использоваться в более старых версиях Discourse.

Теперь любой пользователь более старой версии Discourse (например, 3.2.0.beta1 или 3.1.4) будет использовать версию abcde вашей темы или плагина. Пользователи версии 3.2.0.beta2-dev и выше продолжат использовать последнюю версию.

Несколько записей

Со временем вы можете добавлять несколько строк в файл .discourse-compatibility. Discourse всегда будет выбирать «наименьшую» спецификацию, соответствующую текущей версии ядра Discourse. Порядок строк в файле технически не имеет значения, но мы рекомендуем располагать самые свежие записи вверху.

«Бэкпортирование» изменений для старых версий Discourse

Представим файл .discourse-compatibility следующего вида с двумя различными спецификациями версий, закреплёнными за конкретными коммитами плагина:

< 3.2.0.beta1-dev: commithashfordiscourse31
< 3.1.0.beta1-dev: commithashfordiscourse30

Если вам нужно «бэкпортировать» изменение для Discourse 3.1, выполните следующие шаги:

1. Создайте ветку на основе старого коммита (git checkout -b my_branch_name commithashfordiscourse31).

2. Сделайте коммит вашего изменения и отправьте его в удалённый репозиторий. Если вы используете функции защиты веток GitHub, рекомендуется защитить эту ветку от случайного удаления.

3. Обновите файл .discourse-compatibility в главной ветке, чтобы он указывал на ваш новый коммит в ветке поддержки версии 3.1.

Пример из реальной жизни

Вот реальный файл .discourse-compatibility из плагина discourse-solved. Обратите внимание, что на момент написания этой статьи он всё ещё использует «устаревший» синтаксис без явных операторов < или <=. Поэтому каждая строка автоматически интерпретируется как <=.

.discourse-compatibility

---

Этот документ находится под версионным контролем — предлагайте изменения на GitHub.

[NateDhaliwal]

If the version is < 3.5.0.beta8-dev, would it include 3.5.0?

[david (David Taylor)]

No. 3.5.0 is considered “higher” than the prerelease version “3.5.0.beta8-dev”.

You can always try out comparisons on a ruby console:

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

[NateDhaliwal]

Understood. Thanks for the explanation!