Atualizar EmDash

Este guia é para operadores do site: pessoas que executam um site baseado em EmDash e querem colocá-lo em uma release mais recente. Cobre o pacote emdash e @emdash-cms/cloudflare. Pacotes de plugins têm o próprio guia, Atualizar plugins no seu site, e alterações nas suas próprias collections e campos estão em Evoluir um site implantado.

Releases e números de versão

EmDash é lançado antes da versão 1.0, e seus números de versão seguem duas regras:

• Uma release de patch, por exemplo de 0.35.0 para 0.35.1, traz correções de bugs e pequenas melhorias.
• Uma release menor, por exemplo de 0.35 para 0.36, traz novos recursos e qualquer mudança incompatível. Uma mudança incompatível é marcada Breaking na sua entrada de release, e a entrada declara a ação que exige de você.

emdash e @emdash-cms/cloudflare são lançados juntos e compartilham um número de versão. @emdash-cms/cloudflare depende da versão exata correspondente de emdash, então atualize os dois pacotes em um passo. Pacotes de plugins 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. Antes de uma atualização, leia as entradas emdash entre a versão instalada e o alvo, e o mesmo intervalo para @emdash-cms/cloudflare se o site roda na Cloudflare.

Antes de atualizar

Faça um backup restaurável do banco de dados e um backup separado do armazenamento de mídia. A exportação JSON do EmDash não pode restaurar um site, e as migrações do núcleo não têm um passo operacional de desfazer. Backups e recuperação descreve o ponto de recuperação utilizável para cada banco de dados.

Verifique a versão do Node.js na máquina que compila o site e, para um deployment Node.js, no servidor. Primeiros passos lista as versões suportadas.

Atualizar os pacotes

Os comandos abaixo usam pnpm e um site criado a partir de um template Cloudflare. Para um deployment Node.js, omita @emdash-cms/cloudflare.

Implantar e verificar

Implante a build da mesma forma que qualquer outra alteração. O comando a seguir implanta um site Cloudflare; para um deployment Node.js, reinicie o processo do servidor com a nova build.

pnpm wrangler deploy

Com o modo de migração de runtime padrão, auto, o site implantado aplica migrações do núcleo pendentes na primeira requisição. Para aplicá-las antes que o novo código receba tráfego, e para verificar o banco implantado depois, siga Gerenciar migrações do banco de dados do núcleo. Seu comando emdash migrate --check termina com código diferente de zero quando o banco implantado tem migrações pendentes ou desconhecidas para a versão instalada.

Após o 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 sandboxed, verifique esses caminhos também.

Notas para releases específicas

A maioria das releases não precisa de nada além dos passos acima. As entradas abaixo cobrem releases que alteraram dados que EmDash já armazenava, e dizem 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 na tabela da sua collection, e nomeava a collection de destino em uma opção de campo que o painel de administração não podia definir.

Um campo de referência agora é um seletor de entradas respaldado por uma relation, e seus links vivem fora da tabela da collection. A atualização vincula cada campo de referência que nomeava uma collection de destino a uma nova relation e copia os IDs de entrada da sua coluna como links, de modo que o campo se torna um seletor com a seleção intacta. A coluna fica no lugar e a atualização não exclui nada.

Um campo fica sem vínculo quando:

• não nomeia uma collection de destino, ou nomeia uma que não existe mais
• está marcado searchable ou indexed
• precisa do slug de relation {collection}_{field} e esse slug já está ocupado
• seleciona entradas diferentes em locales diferentes da mesma entrada, em qualquer entrada

Esse último ponto é sobre onde os links vivem. Um link 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 carregar — mesclá-los 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 em paz e ambos os 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 entrada selecionaram essa entrada uma vez, então a atualização vincula o campo e o link resolve para a própria versão 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 cada tradução, incluindo a vazia.

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

O que devo fazer?

Abra uma entrada em cada collection que tenha um campo de referência. Um campo que renderiza como seletor não precisa de nada. Para um campo que ainda renderiza como caixa de texto, siga Vincular um campo que não tem relation, que cria a relation e copia os IDs armazenados do campo como links. Em um site multi-locale, defina para qual entrada cada tradução deve apontar antes de vincular, pois vincular mantém uma seleção para todas.

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

• A build falha, ou uma página sua dá erro em runtime: leia as entradas de release marcadas Breaking das versões que você pulou e faça as alterações que elas declararem.
• Um plugin não carrega: leia a própria entrada de release do plugin e Atualizar plugins no seu site.
• Um erro nomeia uma API Astro ou um pacote @astrojs/*: EmDash exige Astro 6 ou posterior. O guia de atualização do Astro explica como atualizar astro e suas integrações oficiais juntos.
• Para voltar à release anterior, reinstale as versões de pacote anteriores correspondentes e reimplante esse artefato. Reinstalar não desfaz migrações do núcleo. Se o artefato anterior não puder usar o banco migrado, pare o tráfego e restaure juntos o banco e o artefato pré-atualização; restaure a mídia somente se a atualização a alterou.