Migrar configurações de tema do Discourse

Documentação Guias do Desenvolvedor
1

Introdução

A partir da versão 3.2.0.beta3 do Discourse, os temas/componentes do Discourse podem aproveitar um recurso de migrações para evoluir e alterar suas configurações de forma transparente. Esse recurso garante que as atualizações de temas não interrompam as instalações existentes, lidando com as alterações nas configurações de maneira controlada.

Quando Usar Migrações

Cenários comuns onde as migrações são particularmente úteis:

  • Alterar o tipo de uma configuração (por exemplo, de uma string separada por vírgulas para uma lista).
  • Renomear uma configuração.
  • Modificar a estrutura ou o formato dos dados armazenados em uma configuração.

Nesses cenários, se o tipo ou nome da configuração for alterado no arquivo settings.yml sem uma migração correspondente, as instalações existentes onde a configuração foi alterada do valor padrão perderão a alteração feita e potencialmente quebrarão quando o tema for atualizado.

Para garantir uma transição suave ao atualizar uma configuração de tema, os desenvolvedores de temas devem fornecer uma migração que instrua o núcleo do Discourse sobre como migrar o estado existente que está em conformidade com a versão antiga do settings.yml para a nova versão.

Arquivos de Migração

As migrações são arquivos JavaScript localizados no diretório migrations/settings do tema, seguindo a convenção de nomenclatura XXXX-nome-da-migracao.js. O prefixo XXXX é um número de versão, começando em 0001 e incrementando sequencialmente, o que dita a ordem de execução.

O nome deve ser uma descrição concisa do propósito da migração, limitado a caracteres alfanuméricos, hifens e com menos de 150 caracteres de comprimento. As migrações são executadas em ordem crescente com base no valor numérico de suas versões.

Recomendamos que você comece com 0001 para a primeira migração e 0002 para a segunda migração, etc. Observe que, se a versão de uma migração for inferior a 1000, a versão deve ser preenchida com zeros à esquerda para que tenha 4 dígitos, pois o nome do arquivo de migração deve começar com 4 dígitos. Pelo mesmo motivo, atualmente não é possível ter mais de 9999 migrações em um tema, mas podemos mudar isso no futuro.

Função de Migração

Recursos padrão do JavaScript features como classes, funções, arrays, mapas, etc., estão todos disponíveis para uso nas migrações. A única expectativa do núcleo do Discourse é que cada arquivo de migração deve exportar uma função padrão que serve como ponto de entrada. Essa função recebe um objeto Map representando as configurações de tema modificadas e retorna um objeto Map refletindo o estado final desejado de todas as configurações.

Exemplos

Renomear uma configuração de tema:

// 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;
}

Esta migração deve ser acompanhada pela renomeação da configuração no arquivo settings.yml.

Converter uma configuração de string separada por vírgulas para uma lista adequada:

// 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;
}

Semelhante ao exemplo anterior, esta migração deve ser acompanhada pela alteração do tipo de configuração de string para list no arquivo settings.yml.

Renomear uma opção de uma configuração de enumeração:

// 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;
}

Adicionar um novo item a uma configuração de lista:

// 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;
}

Execução e Tratamento de Erros

As migrações são executadas automaticamente durante a instalação e atualização de temas. Elas são executadas apenas uma vez; se uma migração for alterada após a execução bem-sucedida, ela não será executada novamente. Se uma migração falhar, o processo de atualização para e uma mensagem de erro sobre o que deu errado é fornecida.

Se uma migração tiver um bug que resulte em um estado corrompido para uma configuração, a maneira correta de corrigir o problema é criar uma nova migração que corrija o estado corrompido em vez de modificar a migração original.

Este documento é controlado por versão - sugira alterações no github.

8 curtidas