Migrer les paramètres du thème Discourse

Documentation Guides pour les développeurs
1

Introduction

À partir de la version 3.2.0.beta3 de Discourse, les thèmes/composants Discourse 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 modifications des paramètres de manière contrôlée.

Quand utiliser les migrations

Scénarios courants où les migrations sont particulièrement utiles :

  • Modification du type d’un paramètre (par exemple, d’une chaîne de caractères séparée par des virgules à une liste).
  • Renommage d’un paramètre.
  • Modification de la structure ou du 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 à la valeur par défaut perdront la modification qu’ils ont apportée au paramètre et risquent de planter 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 à Discourse core comment migrer l’état existant qui correspond à 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-nom-de-la-migration.js. Le préfixe XXXX est un numéro de version, commençant par 0001 et s’incrémentant séquentiellement, ce qui détermine 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 dans l’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 migration, etc. Notez que si la version d’une migration est inférieure à 1000, la version doit être complétée par des zéros en tête pour qu’elle ait 4 chiffres, car le nom de fichier de 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 nous pourrions changer cela à l’avenir.

Fonction de migration

Les fonctionnalités JavaScript standard telles que les classes, les fonctions, les tableaux, les maps, etc., sont toutes disponibles pour les migrations. La seule attente de Discourse core est que chaque fichier de migration doit exporter 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 renvoie un objet Map reflétant l’état final souhaité de tous les paramètres.

Exemples

Renommer un paramètre de thème :

// nom du fichier : 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 de caractères séparée par des virgules en une liste appropriée :

// nom du fichier : 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 de la modification du type de paramètre de string à list dans le fichier settings.yml.

Renommer un choix d’un paramètre d’énumération :

// nom du fichier : 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 :

// nom du fichier : 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 pas à nouveau. Si une migration échoue, le processus de mise à jour s’arrête et un message d’erreur expliquant ce qui s’est mal passé est fourni.

Si une migration contient un bug qui entraîne un état corrompu pour un paramètre, la bonne façon de résoudre le problème est de créer une nouvelle migration qui corrige l’état corrompu au lieu de modifier la migration d’origine.

Ce document est contrôlé par version - suggérez des modifications sur github.

8 « J'aime »