Atualizar EmDash

Este guia é para operadores de sites: pessoas que mantêm um site construído com o EmDash e querem levá-lo para uma versão mais recente. O atualizador cobre todas as dependências diretas de emdash e @emdash-cms/* do projeto. As mudanças nas suas próprias coleções e campos são tratadas em Evoluir o esquema de um site implantado.

Compatibilidade entre releases

O EmDash segue o versionamento semântico:

• Um release de patch traz correções e pequenas melhorias compatíveis com versões anteriores.
• Um release minor traz recursos compatíveis com versões anteriores.
• Um release major pode exigir mudanças em um projeto existente. Suas entradas de release identificam os projetos afetados e as ações necessárias.

emdash e @emdash-cms/cloudflare são lançados juntos e compartilham um único número de versão. @emdash-cms/cloudflare depende da versão exatamente correspondente de emdash, então atualize os dois pacotes em uma única etapa. Pacotes de plugin como @emdash-cms/plugin-forms têm seus próprios números de versão e declaram a versão mínima de emdash de que precisam.

A página de releases tem uma entrada por pacote e versão. O upgrade-emdash obtém o intervalo do changelog de cada pacote direto a partir da tag de release exata do GitHub. Ele remove as entradas geradas de atualização de dependências, preserva por completo as entradas major, minor e patch escritas à mão e elimina as entradas repetidas entre pacotes.

Os arquivos de template não são atualizados

Criar um site a partir de um template copia para o seu projeto os arquivos do template, como layouts, componentes, estilos e astro.config.mjs. O atualizador altera as dependências diretas do EmDash e atualiza as agent skills do EmDash. Ele deixa os arquivos de aplicação e de configuração do site para o responsável pelo projeto ou para um agente alterar a partir da ordem de trabalho da atualização. Mudanças posteriores em um template se aplicam apenas a sites novos. Para adotar uma em um site existente, compare seus arquivos com a versão atual no diretório templates e copie as mudanças que quiser.

Antes de atualizar

O atualizador altera arquivos do projeto e pacotes instalados sem se conectar ao banco de dados do site, então não exige um backup específico para a atualização antes de ser executado. Depois da instalação, .emdash/UPGRADE.md identifica as migrações do núcleo adicionadas, se houver.

Antes de iniciar ou implantar a aplicação atualizada, crie um ponto de recuperação quando a ordem de trabalho listar migrações adicionadas, emdash migrate --status informar uma migração anterior pendente ou uma entrada de release exigir uma ação de projeto que altere dados. Siga Backups e recuperação para o banco de dados configurado. O backup JSON do EmDash não consegue restaurar um site.

O atualizador exige emdash 0.35.0 ou posterior, o primeiro release que informa suas migrações do núcleo. Para um site mais antigo, crie um ponto de recuperação, atualize emdash e os demais pacotes diretos @emdash-cms/* para a 0.35.0 com o gerenciador de pacotes do projeto e revise os changelogs dos pacotes até esse release. Depois execute o atualizador para o restante da atualização.

O atualizador lê os pacotes de node_modules, então não oferece suporte a instalações do Yarn Plug’n’Play. Em um projeto Yarn que usa Plug’n’Play, defina nodeLinker: node-modules em .yarnrc.yml e execute yarn install antes de executar o atualizador.

Verifique a versão do Node.js na máquina que constrói o site e, em uma implantação com Node.js, no servidor. Criar seu primeiro site EmDash lista as versões compatíveis.

Planejar e aplicar a atualização

Execute o atualizador a partir do diretório do projeto do site. Ele lê as versões dos pacotes instalados e a identidade das migrações do núcleo e, em seguida, resolve separadamente o dist-tag do npm selecionado para cada pacote direto do EmDash. A tag padrão é latest; use --to next, --to beta ou outro dist-tag para escolher um canal de releases. --to não aceita uma versão exata.

Implantar e verificar

Implante o build da mesma forma que qualquer outra mudança. O comando a seguir implanta um site no Cloudflare; em um deploy com Node.js, reinicie o processo do servidor com o novo build.

pnpm wrangler deploy

Com o modo de migração em tempo de execução padrão, auto, o site implantado aplica as migrações do núcleo pendentes na primeira requisição. Não implante um build com migrações pendentes até que o ponto de recuperação necessário exista. Para aplicar as migrações antes que o novo código receba tráfego, e para verificar o banco de dados implantado depois, siga Gerenciar migrações do banco de dados do núcleo. O comando emdash migrate --check encerra com código diferente de zero quando o banco de dados implantado tem migrações pendentes ou desconhecidas para a versão instalada.

Depois do deploy, abra o admin, carregue pelo menos uma página pública, edite e publique uma entrada descartável, e envie e recupere um arquivo de mídia descartável. Se o site usa tarefas agendadas ou plugins em sandbox, verifique esses caminhos também.

Notas para releases específicas

A maioria dos releases não precisa de nada além das etapas acima. As entradas abaixo cobrem os releases que alteraram dados que o EmDash já armazenava, e informam quando isso exige uma ação sua.

Alterado: campos de referência vinculam-se a relations

Um campo reference costumava guardar o ID da entrada de destino em uma coluna da tabela da sua coleção, e nomeava a coleção de destino em uma opção de campo que o painel de administração não conseguia definir.

Um campo de referência agora é um seletor de entradas apoiado por uma relação, e seus vínculos ficam fora da tabela da coleção. A atualização vincula cada campo de referência que nomeava uma coleção de destino a uma nova relação e copia para ela, como vínculos, os IDs de entrada da sua coluna, de modo que o campo vira um seletor com a seleção intacta. A coluna é deixada onde está e a atualização não exclui nada.

Um campo permanece sem vínculo quando:

• não nomeia nenhuma coleção de destino, ou nomeia uma que não existe mais
• está marcado como pesquisável ou indexado
• precisa do slug de relação {collection}_{field} e esse slug já está em uso
• seleciona entradas diferentes em locales diferentes da mesma entrada, em qualquer entrada

Essa última condição diz respeito a onde os vínculos ficam. Um vínculo pertence ao grupo de tradução de uma entrada, então uma seleção é compartilhada por todas as suas traduções, enquanto a coluna antiga era por locale. Um campo cujos locales discordam não tem uma única seleção para transportar — mesclá-las daria a cada locale as entradas do outro, e escolher a resposta de um locale descartaria o resto —, então a atualização deixa o campo como está e os dois valores legíveis na coluna.

Dois casos que parecem discordância não são. Locales que nomeiam suas próprias traduções de uma mesma entrada selecionaram essa entrada uma única vez, então a atualização vincula o campo e o vínculo é resolvido para a versão própria de cada locale. Um locale que não selecionou nada não contradiz nenhum outro locale, então a atualização vincula o campo e a única seleção do grupo se aplica a todas as traduções, inclusive à vazia.

Um campo sem vínculo continua se comportando como antes. Sua coluna guarda o ID da entrada, o valor é salvo e carregado, e o campo ainda pode ser indexado e usado como filtro da lista de conteúdo. No editor de entradas, ele aparece como uma caixa de texto em vez de um seletor.

O que devo fazer?

Abra uma entrada em cada coleção que tenha um campo de referência. Um campo que aparece como seletor não precisa de nada. Para um campo que ainda aparece como caixa de texto, siga Vincular um campo que não tem relação, que cria a relação e copia para ela, como vínculos, os IDs armazenados do campo. Em um site com vários locales, decida para qual entrada cada tradução deve apontar antes de vincular, já que vincular mantém uma única seleção para todas.

Se o site quebrar após uma atualização

• O build falha, ou uma página sua dá erro em tempo de execução: leia as entradas de release marcadas como Breaking das versões que você pulou e faça as mudanças que elas indicam.
• Um plugin não carrega: leia a entrada de release do próprio plugin e Atualizando plugins no seu site.
• Um erro cita uma API do Astro ou um pacote @astrojs/*: o EmDash exige Astro 6 ou posterior. O guia de atualização do Astro explica como atualizar astro e suas integrações oficiais em conjunto.
• Para voltar ao release anterior, reinstale as versões anteriores correspondentes dos pacotes e implante esse artefato novamente. Reinstalar não desfaz as migrações do núcleo. Se o artefato anterior não consegue usar o banco de dados migrado, pare o tráfego e restaure juntos o banco de dados anterior à atualização e o artefato; restaure a mídia somente se a atualização a alterou.