Введение
Начиная с версии Discourse 3.2.0.beta3, темы и компоненты Discourse могут использовать функцию миграций для плавной эволюции и изменения своих настроек. Эта функция гарантирует, что обновления тем не нарушают работу существующих установок, контролируемым образом обрабатывая изменения настроек.
Когда использовать миграции
Распространенные сценарии, где миграции особенно полезны:
- Изменение типа настройки (например, из строки с запятыми в список).
- Переименование настройки.
- Изменение структуры или формата данных, хранящихся в настройке.
В этих сценариях, если тип или имя настройки изменены в файле settings.yml без сопутствующей миграции, то в существующих установках, где настройка была изменена по сравнению со значением по умолчанию, пользователи потеряют свои изменения, и тема может сломаться при обновлении.
Чтобы обеспечить плавный переход при обновлении настройки темы, разработчики тем должны поставлять миграцию, которая инструктирует ядро Discourse о том, как перенести существующие данные, соответствующие старой версии settings.yml, в новую версию.
Файлы миграций
Миграции представляют собой файлы JavaScript, расположенные в директории migrations/settings темы, следуя соглашению об именовании XXXX-name-of-migration.js. Префикс XXXX является номером версии, начиная с 0001 и последовательно увеличиваясь, и определяет порядок выполнения.
Имя должно быть кратким описанием назначения миграции, ограниченным алфавитно-цифровыми символами, дефисами и длиной менее 150 символов. Миграции выполняются в порядке возрастания на основе числового значения их версий.
Мы рекомендуем начинать с 0001 для первой миграции, 0002 для второй и так далее. Обратите внимание, что если версия миграции меньше 1000, она должна быть дополнена ведущими нулями до 4 цифр, так как имя файла миграции должно начинаться с 4 цифр. По той же причине в настоящее время невозможно иметь более 9999 миграций в теме, но мы можем изменить это в будущем.
Функция миграции
Стандартные возможности JavaScript, такие как классы, функции, массивы, карты и т.д., доступны для использования в миграциях. Единственное требование со стороны ядра Discourse: каждый файл миграции должен экспортировать функцию по умолчанию, которая служит точкой входа. Эта функция получает объект Map, представляющий измененные настройки темы, и возвращает объект Map, отражающий желаемое конечное состояние всех настроек.
Примеры
Переименовать настройку темы:
// filename: 0001-rename-old-setting.js
export default function migrate(settings) {
if (settings.has("old_setting_name")) {
settings.set("new_setting_name", settings.get("old_setting_name"));
settings.delete("old_setting_name");
}
return settings;
}
Эта миграция должна сопровождаться переименованием настройки в файле settings.yml.
Преобразовать строку, разделенную запятыми, в правильный список:
// filename: 0001-convert-string-setting-to-list.js
export default function migrate(settings) {
if (settings.has("list_setting")) {
const list = settings.get("list_setting").split(",");
settings.set("list_setting", list.join("|"));
}
return settings;
}
Подобно предыдущему примеру, эта миграция должна сопровождаться изменением типа настройки с string на list в файле settings.yml.
Переименовать вариант выбора настройки enum:
// filename: 0001-rename-enum-choice.js
export default function migrate(settings) {
if (settings.get("enum_setting") === "old_option") {
settings.set("enum_setting", "new_option");
}
return settings;
}
Добавить новый элемент в настройку-список:
// filename: 0001-add-item-to-list.js
export default function migrate(settings) {
if (settings.has("list_setting")) {
const list = settings.get("list_setting").split("|");
list.push("new_item");
settings.set("list_setting", list.join("|"));
} else {
settings.set("list_setting", "new_item");
}
return settings;
}
Переместить текстовую настройку в перевод темы
Используйте helpers.migrateSettingToTranslation(settingName, translationKey) при замене строковой настройки на перевод темы:
// filename: 0002-migrate-heading.js
export default function migrate(settings, helpers) {
helpers.migrateSettingToTranslation("heading_text", "homepage.heading");
return settings;
}
Удалите heading_text из settings.yml и объявите назначение в locales/en.yml в том же обновлении:
en:
homepage:
heading: ""
Хелпер перемещает сохраненное значение настройки в переопределение английского перевода темы и удаляет настройку. Английский язык является резервным для других языков, поэтому посетители продолжат видеть сохраненный текст, пока не будет предоставлен перевод для их локали. Файл локали, который объявляет тот же ключ, даже с пустым значением, скрывает этот сохраненный английский текст для своей локали. Это также применяется к файлам локалей, добавленным в будущих обновлениях.
- Хелпер считывает данные из карты
settings, переданной в миграцию. Мигрируются только сохраненные настройки. Если у старой настройки было непустое значение по умолчанию, используйте это значение по умолчанию вen.yml, чтобы сайты без сохраненного значения сохраняли свой текст. - Значение настройки должно быть строкой, а назначение — объявленным текстовым ключом. Пустые строки сохраняются.
- Существующие английские переопределения, включая пустые, не перезаписываются. Если несколько миграций нацелены на один и тот же ключ, выигрывает первое мигрированное значение.
- Выполнитель сохраняет изменения переводов без записи в базу данных. Discourse сохраняет их в той же транзакции, что и настройки и записи миграций; при ошибке обновления происходит откат всего.
- Журнал миграций сохраняет значение удаленной настройки. Откат кода темы не перемещает переопределения переводов обратно в настройки.
Выполнение и обработка ошибок
Миграции запускаются автоматически при установке и обновлении тем. Они выполняются только один раз; если миграция изменена после успешного выполнения, она не будет запущена снова. Если миграция завершается ошибкой, процесс обновления останавливается, и предоставляется сообщение об ошибке.
Если в миграции есть ошибка, приводящая к повреждению состояния настройки, правильным способом исправить проблему является создание новой миграции, исправляющей поврежденное состояние, вместо модификации оригинальной миграции.
Этот документ находится под контролем версий — предложите изменения на github.