Introduction
Depuis la version 3.2.0.beta3 de Discourse, les thèmes/composants peuvent exploiter une fonctionnalité de migrations pour faire évoluer et modifier leurs paramètres de manière transparente. Cette fonctionnalité garantit que les mises à jour des thèmes ne perturbent pas les installations existantes en gérant les changements de paramètres de manière contrôlée.
Quand utiliser les migrations
Scénarios courants où les migrations sont particulièrement utiles :
- Changer le type d’un paramètre (par exemple, d’une chaîne séparée par des virgules à une liste).
- Renommer un paramètre.
- Modifier la structure ou le format des données stockées dans un paramètre.
Dans ces scénarios, si le type ou le nom du paramètre est modifié dans le fichier settings.yml sans migration correspondante, les installations existantes où le paramètre a été modifié par rapport à sa valeur par défaut perdront cette modification et risquent de rencontrer des problèmes lors de la mise à jour du thème.
Pour assurer une transition en douceur lors de la mise à jour d’un paramètre de thème, les développeurs de thèmes doivent fournir une migration qui indique au cœur de Discourse comment migrer l’état existant conforme à l’ancienne version du settings.yml vers la nouvelle version.
Fichiers de migration
Les migrations sont des fichiers JavaScript situés dans le répertoire migrations/settings du thème, suivant la convention de nommage XXXX-migration-name.js. Le préfixe XXXX est un numéro de version, commençant par 0001 et s’incrémentant séquentiellement, ce qui dicte l’ordre d’exécution.
Le nom doit être une description concise de l’objectif de la migration, limité aux caractères alphanumériques, aux tirets, et à moins de 150 caractères. Les migrations sont exécutées par ordre croissant en fonction de la valeur numérique de leurs versions.
Nous vous recommandons de commencer par 0001 pour la première migration et 0002 pour la deuxième, etc. Notez que si la version d’une migration est inférieure à 1000, la version doit être complétée par des zéros non significatifs pour atteindre 4 chiffres, car le nom de fichier de la migration doit commencer par 4 chiffres. Pour la même raison, il n’est actuellement pas possible d’avoir plus de 9999 migrations dans un thème, mais cela pourrait changer à l’avenir.
Fonction de migration
Les fonctionnalités standard de JavaScript telles que les classes, les fonctions, les tableaux, les maps, etc., sont toutes disponibles pour être utilisées par les migrations. La seule attente du cœur de Discourse est que chaque fichier de migration exporte une fonction par défaut qui sert de point d’entrée. Cette fonction reçoit un objet Map représentant les paramètres de thème modifiés et retourne un objet Map reflétant l’état final souhaité de tous les paramètres.
Exemples
Renommer un paramètre de thème :
// 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;
}
Cette migration doit être accompagnée du renommage du paramètre dans le fichier settings.yml.
Convertir un paramètre de chaîne séparée par des virgules en une liste appropriée :
// 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;
}
Semblable à l’exemple précédent, cette migration doit être accompagnée du changement du type de paramètre de string à list dans le fichier settings.yml.
Renommer un choix d’un paramètre 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;
}
Ajouter un nouvel élément à un paramètre de liste :
// 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;
}
Exécution et gestion des erreurs
Les migrations s’exécutent automatiquement lors de l’installation et des mises à jour des thèmes. Elles ne s’exécutent qu’une seule fois ; si une migration est modifiée après une exécution réussie, elle ne s’exécutera plus. Si une migration échoue, le processus de mise à jour s’arrête et un message d’erreur indiquant ce qui s’est mal passé est fourni.
Si une migration contient un bogue qui entraîne un état corrompu pour un paramètre, la manière correcte de corriger le problème est de créer une nouvelle migration qui corrige l’état corrompu au lieu de modifier la migration originale.
Ce document est contrôlé par version - suggérez des modifications sur github.