Introduction
Discourse 버전 3.2.0.beta3부터 Discourse 테마/컴포넌트는 마이그레이션(migrations) 기능을 활용할 수 있으며, 이를 통해 설정을 원활하게 진화 및 변경할 수 있습니다. 이 기능은 설정 변경 사항을 제어된 방식으로 처리하여 테마 업데이트가 기존 설치 환경에 혼란을 주지 않도록 보장합니다.
마이그레이션 사용 시점
마이그레이션이 특히 유용한 일반적인 시나리오는 다음과 같습니다:
- 설정의 유형 변경 (예: 쉼표로 구분된 문자열에서 목록으로 변경).
- 설정 이름 변경.
- 설정에 저장된 데이터의 구조 또는 형식 변경.
이러한 시나리오에서 settings.yml 파일에서 설정 유형이나 이름을 변경하면서 마이그레이션을 함께 제공하지 않으면, 기본값에서 설정이 변경된 기존 설치 환경에서는 사용자가 설정에 대해 수행한 변경 사항이 손실되고 테마 업데이트 시 잠재적으로 오류가 발생할 수 있습니다.
테마 설정 업데이트 시 원활한 전환을 보장하기 위해, 테마 개발자는 기존 settings.yml 버전의 상태가 새 버전으로 마이그레이션되도록 Discourse 코어에 지시하는 마이그레이션을 제공해야 합니다.
마이그레이션 파일
마이그레이션은 테마의 migrations/settings 디렉토리에 위치하는 JavaScript 파일이며, XXXX-migration-name.js라는 명명 규칙을 따릅니다. XXXX 접두사는 실행 순서를 결정하는 버전 번호로, 0001부터 순차적으로 증가합니다.
이름은 마이그레이션의 목적을 간결하게 설명하는 것으로, 알파벳, 숫자, 하이픈만 사용할 수 있으며 길이는 150자 미만이어야 합니다. 마이그레이션은 버전의 숫자 값 기준으로 오름차순으로 실행됩니다.
첫 번째 마이그레이션은 0001, 두 번째는 0002 등으로 시작하는 것을 권장합니다. 마이그레이션 버전이 1000 미만인 경우, 마이그레이션 파일 이름은 4자리로 시작해야 하므로 버전은 앞쪽에 0을 채워 4자리로 만들어야 합니다. 동일한 이유로 현재 테마당 9999개 이상의 마이그레이션을 가질 수는 없지만, 미래에 이 부분이 변경될 수 있습니다.
마이그레이션 함수
클래스, 함수, 배열, 맵 등 표준 JavaScript 기능은 마이그레이션에서 모두 사용할 수 있습니다. Discourse 코어가 요구하는 유일한 조건은 각 마이그레이션 파일이 엔트리 포인트 역할을 하는 기본 함수(default function)를 내보내야 한다는 것입니다. 이 함수는 수정된 테마 설정을 나타내는 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;
}
이전 예제와 마찬가지로, 이 마이그레이션은 settings.yml 파일에서 설정 유형을 string에서 list로 변경하는 작업과 함께 제공되어야 합니다.
열거형(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;
}
실행 및 오류 처리
마이그레이션은 테마 설치 및 업데이트 중에 자동으로 실행됩니다. 마이그레이션은 한 번만 실행되며, 성공적으로 실행된 후 마이그레이션이 변경되더라도 다시 실행되지 않습니다. 마이그레이션이 실패하면 업데이트 프로세스가 중단되고 무엇이 잘못되었는지에 대한 오류 메시지가 제공됩니다.
마이그레이션에 버그가 있어 설정의 상태가 손상된 결과를 초래하는 경우, 문제를 해결하는 올바른 방법은 원래 마이그레이션을 수정하는 대신 손상된 상태를 수정하는 새 마이그레이션을 만드는 것입니다.
이 문서는 버전 관리됩니다. 변경 사항을 github에서 제안해 주세요.