Migrar la configuración del tema de Discourse

Introducción

Desde la versión 3.2.0.beta3 de Discourse, los temas y componentes de Discourse pueden aprovechar una función de migraciones para evolucionar y modificar sus ajustes de forma fluida. Esta función garantiza que las actualizaciones de los temas no interrumpan las instalaciones existentes al gestionar los cambios en los ajustes de manera controlada.

Cuándo usar migraciones

Escenarios comunes donde las migraciones son particularmente útiles:

  • Cambiar el tipo de un ajuste (por ejemplo, de una cadena separada por comas a una lista).
  • Renombrar un ajuste.
  • Modificar la estructura o formato de los datos almacenados en un ajuste.

En estos escenarios, si se cambia el tipo o nombre del ajuste en el archivo settings.yml sin una migración acompañante, las instalaciones existentes donde el ajuste haya sido modificado respecto al valor predeterminado perderán el cambio realizado y podrían dejar de funcionar cuando se actualice el tema.

Para garantizar una transición fluida al actualizar un ajuste de tema, los desarrolladores de temas deben incluir una migración que indique al núcleo de Discourse cómo migrar el estado existente que cumple con la versión anterior de settings.yml a la nueva versión.

Archivos de migración

Las migraciones son archivos JavaScript ubicados en el directorio migrations/settings del tema, siguiendo la convención de nomenclatura XXXX-nombre-de-la-migracion.js. El prefijo XXXX es un número de versión, comenzando por 0001 y aumentando secuencialmente, que dicta el orden de ejecución.

El nombre debe ser una descripción concisa del propósito de la migración, limitada a caracteres alfanuméricos, guiones y una longitud inferior a 150 caracteres. Las migraciones se ejecutan en orden ascendente según el valor numérico de sus versiones.

Recomendamos comenzar con 0001 para la primera migración y 0002 para la segunda, y así sucesivamente. Tenga en cuenta que si la versión de una migración es inferior a 1000, la versión debe rellenarse con ceros iniciales para que tenga 4 dígitos, ya que el nombre del archivo de migración debe comenzar con 4 dígitos. Por la misma razón, actualmente no es posible tener más de 9999 migraciones en un tema, aunque esto podría cambiar en el futuro.

Función de migración

Todas las funcionalidades estándar de JavaScript, como clases, funciones, arrays, maps, etc., están disponibles para su uso en las migraciones. La única expectativa por parte del núcleo de Discourse es que cada archivo de migración debe exportar una función predeterminada que sirva como punto de entrada. Esta función recibe un objeto Map que representa los ajustes del tema modificados y devuelve un objeto Map que refleja el estado final deseado de todos los ajustes.

Ejemplos

Renombrar un ajuste de tema:

// nombre del archivo: 0001-renombrar-ajuste-viejo.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;
}

Esta migración debe acompañarse del cambio de nombre del ajuste en el archivo settings.yml.


Convertir un ajuste de cadena separada por comas a una lista apropiada:

// nombre del archivo: 0001-convertir-ajuste-cadena-a-lista.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;
}

Similar al ejemplo anterior, esta migración debe acompañarse del cambio del tipo de ajuste de string a list en el archivo settings.yml.


Renombrar una opción de un ajuste enum:

// nombre del archivo: 0001-renombrar-opcion-enum.js

export default function migrate(settings) {
  if (settings.get("enum_setting") === "old_option") {
    settings.set("enum_setting", "new_option");
  }
  return settings;
}

Añadir un nuevo elemento a un ajuste de lista:

// nombre del archivo: 0001-anadir-elemento-a-lista.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;
}

Mover un ajuste de texto a una traducción del tema

Use helpers.migrateSettingToTranslation(settingName, translationKey) cuando reemplace un ajuste de cadena con una traducción del tema:

// nombre del archivo: 0002-migrar-encabezado.js
export default function migrate(settings, helpers) {
  helpers.migrateSettingToTranslation("heading_text", "homepage.heading");
  return settings;
}

Elimine heading_text de settings.yml y declare el destino en locales/en.yml en la misma actualización:

en:
  homepage:
    heading: ""

El ayudante mueve un ajuste guardado a una anulación de traducción del tema en inglés y elimina el ajuste. El inglés es la configuración regional de reserva para otros idiomas, por lo que los visitantes siguen viendo el texto guardado hasta que se proporcione una traducción para su configuración regional. Un archivo de idioma que declare la misma clave, incluso con un valor vacío, oculta ese texto en inglés guardado para su configuración regional. Esto también se aplica a los archivos de idioma añadidos en actualizaciones futuras.

  • El ayudante lee del mapa settings pasado a la migración. Solo se migran los ajustes guardados. Si el ajuste anterior tenía un valor predeterminado no vacío, use ese valor predeterminado en en.yml para que los sitios sin un valor guardado conserven su texto.
  • El valor del ajuste debe ser una cadena y el destino debe ser una clave de texto declarada. Las cadenas vacías se preservan.
  • Las anulaciones existentes en inglés, incluidas las vacías, no se sobrescriben. Si varias migraciones apuntan a la misma clave, el primer valor migrado tiene prioridad.
  • El ejecutor prepara los cambios de traducción sin escribir en la base de datos. Discourse los guarda en la misma transacción que los ajustes y los registros de migración; una actualización fallida revierte todo.
  • El registro de migración conserva el valor del ajuste eliminado. Revertir el código del tema no mueve las anulaciones de traducción de nuevo a los ajustes.

Ejecución y manejo de errores

Las migraciones se ejecutan automáticamente durante la instalación y actualización de temas. Se ejecutan solo una vez; si una migración se altera después de una ejecución exitosa, no se ejecutará de nuevo. Si una migración falla, el proceso de actualización se detiene y se proporciona un mensaje de error sobre qué salió mal.

Si una migración tiene un error que resulta en un estado corrupto para un ajuste, la forma correcta de solucionar el problema es crear una nueva migración que corrija el estado corrupto en lugar de modificar la migración original.


Este documento está controlado por versiones: sugiera cambios en GitHub.

9 Me gusta