Mettre à jour EmDash

Ce guide s’adresse aux opérateurs de site : les personnes qui font tourner un site basé sur EmDash et veulent le passer à une version plus récente. Il couvre le paquet emdash et @emdash-cms/cloudflare. Les paquets de plugins ont leur propre guide, Mettre à jour les plugins sur votre site, et les changements de vos propres collections et champs sont couverts dans Faire évoluer un site déployé.

Releases et numéros de version

EmDash est publié avant la version 1.0, et ses numéros de version suivent deux règles :

• Une release de correctif, par exemple de 0.35.0 à 0.35.1, apporte des corrections de bugs et de petites améliorations.
• Une release mineure, par exemple de 0.35 à 0.36, apporte de nouvelles fonctionnalités et tout changement cassant. Un changement cassant est marqué Breaking dans son entrée de release, et l’entrée indique l’action qu’il exige de vous.

emdash et @emdash-cms/cloudflare sont publiés ensemble et partagent un numéro de version. @emdash-cms/cloudflare dépend de la version exacte correspondante de emdash, mettez donc à jour les deux paquets en une seule étape. Les paquets de plugins tels que @emdash-cms/plugin-forms ont leurs propres numéros de version et déclarent la version minimale de emdash dont ils ont besoin.

La page des releases a une entrée par paquet et version. Avant une mise à jour, lisez les entrées emdash entre votre version installée et la cible, et la même plage pour @emdash-cms/cloudflare si le site tourne sur Cloudflare.

Avant de mettre à jour

Faites une sauvegarde de base de données restaurable et une sauvegarde séparée du stockage média. L’export JSON d’EmDash ne peut pas restaurer un site, et les migrations du noyau n’ont pas d’étape opérationnelle d’annulation. Sauvegardes et récupération décrit le point de récupération utilisable pour chaque base de données.

Vérifiez la version de Node.js sur la machine qui construit le site et, pour un déploiement Node.js, sur le serveur. Premiers pas liste les versions prises en charge.

Mettre à jour les paquets

Les commandes ci-dessous utilisent pnpm et un site créé à partir d’un modèle Cloudflare. Pour un déploiement Node.js, omettez @emdash-cms/cloudflare.

Déployer et vérifier

Déployez la construction comme toute autre modification. La commande suivante déploie un site Cloudflare ; pour un déploiement Node.js, redémarrez le processus serveur avec la nouvelle construction.

pnpm wrangler deploy

Avec le mode de migration runtime par défaut, auto, le site déployé applique les migrations du noyau en attente à sa première requête. Pour les appliquer avant que le nouveau code ne reçoive du trafic, et pour vérifier la base déployée ensuite, suivez Gérer les migrations de la base de données du noyau. Sa commande emdash migrate --check se termine avec un code non nul lorsque la base déployée a des migrations en attente ou inconnues pour la version installée.

Après le déploiement, ouvrez l’admin, chargez au moins une page publique, modifiez et publiez une entrée jetable, et téléversez et récupérez un fichier média jetable. Si le site utilise des tâches planifiées ou des plugins sandboxed, vérifiez aussi ces chemins.

Notes pour des releases spécifiques

La plupart des releases n’ont besoin de rien au-delà des étapes ci-dessus. Les entrées ci-dessous couvrent les releases qui ont modifié des données qu’EmDash stockait déjà, et indiquent quand cela exige une action de votre part.

Modifié : les champs de référence se lient aux relations

Un champ reference stockait autrefois l’ID de l’entrée cible dans une colonne de la table de sa collection, et nommait sa collection cible dans une option de champ que le panneau d’administration ne pouvait pas définir.

Un champ de référence est désormais un sélecteur d’entrées adossé à une relation, et ses liens vivent en dehors de la table de collection. La mise à jour lie chaque champ de référence qui nommait une collection cible à une nouvelle relation et copie les ID d’entrée de sa colonne en tant que liens, de sorte que le champ devient un sélecteur avec sa sélection intacte. La colonne est laissée en place et la mise à jour ne supprime rien.

Un champ reste non lié lorsqu’il :

• ne nomme aucune collection cible, ou en nomme une qui n’existe plus
• est marqué searchable ou indexed
• a besoin du slug de relation {collection}_{field} et que ce slug est déjà pris
• sélectionne des entrées différentes dans différentes locales de la même entrée, sur n’importe quelle entrée

Ce dernier point concerne l’endroit où vivent les liens. Un lien appartient au groupe de traduction d’une entrée, de sorte qu’une sélection est partagée par toutes ses traductions, tandis que l’ancienne colonne était par locale. Un champ dont les locales sont en désaccord n’a pas de sélection unique à reporter — les fusionner donnerait à chaque locale les entrées de l’autre, et choisir la réponse d’une locale écarterait le reste — donc la mise à jour laisse le champ tranquille et les deux valeurs lisibles dans la colonne.

Deux cas qui ressemblent à un désaccord ne le sont pas. Des locales qui nomment leurs propres traductions d’une entrée ont sélectionné cette entrée une fois, donc la mise à jour lie le champ et le lien se résout vers la propre version de chaque locale. Une locale qui n’a rien sélectionné ne contredit aucune autre locale, donc la mise à jour lie le champ et la seule sélection du groupe s’applique à chaque traduction, y compris la vide.

Un champ non lié continue de se comporter comme avant. Sa colonne contient l’ID d’entrée, la valeur s’enregistre et se charge, et le champ peut toujours être indexé et utilisé comme filtre de liste de contenu. Dans l’éditeur d’entrée, il se rend comme une zone de texte plutôt qu’un sélecteur.

Que dois-je faire ?

Ouvrez une entrée dans chaque collection qui a un champ de référence. Un champ qui se rend comme sélecteur n’a besoin de rien. Pour un champ qui se rend encore comme zone de texte, suivez Lier un champ qui n’a pas de relation, qui crée la relation et copie les ID stockés du champ en tant que liens. Sur un site multi-locale, décidez vers quelle entrée chaque traduction doit pointer avant de lier, car lier conserve une sélection pour toutes.

Si le site casse après une mise à jour

• La construction échoue, ou une de vos pages plante à l’exécution : lisez les entrées de release marquées Breaking pour les versions que vous avez sautées et faites les changements qu’elles indiquent.
• Un plugin ne se charge pas : lisez l’entrée de release propre au plugin et Mettre à jour les plugins sur votre site.
• Une erreur nomme une API Astro ou un paquet @astrojs/* : EmDash exige Astro 6 ou plus récent. Le guide de mise à niveau d’Astro explique comment mettre à jour astro et ses intégrations officielles ensemble.
• Pour revenir à la release précédente, réinstallez les versions de paquet précédentes correspondantes et redéployez cet artefact. La réinstallation n’annule pas les migrations du noyau. Si l’artefact précédent ne peut pas utiliser la base migrée, arrêtez le trafic et restaurez ensemble la base et l’artefact d’avant la mise à jour ; restaurez les médias seulement si la mise à jour les a modifiés.