Mettre à jour EmDash

Ce guide s’adresse aux exploitants de sites : les personnes qui font tourner un site construit 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, et les modifications de vos propres collections et champs sont traitées dans Faire évoluer le schéma d’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 bogues et de petites améliorations.
• Une release mineure, par exemple de 0.35 à 0.36, apporte de nouvelles fonctionnalités et tout changement incompatible. Un changement incompatible est marqué Breaking dans son entrée de release, et l’entrée indique l’action qu’il exige de votre part.

emdash et @emdash-cms/cloudflare sont publiés ensemble et partagent un même numéro de version. @emdash-cms/cloudflare dépend de la version exactement correspondante d’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 d’emdash dont ils ont besoin.

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

Les fichiers de template ne sont pas mis à jour

Créer un site à partir d’un template copie les fichiers du template, tels que les layouts, composants, styles et astro.config.mjs, dans votre projet. Une mise à jour ne modifie que les paquets installés et laisse ces fichiers tels quels. Les modifications ultérieures d’un template ne s’appliquent qu’aux nouveaux sites. Pour en adopter une dans un site existant, comparez vos fichiers avec la version actuelle du répertoire templates et copiez les modifications souhaitées.

Avant de mettre à jour

Effectuez une sauvegarde restaurable de la base de données et une sauvegarde distincte du stockage des médias. L’export JSON d’EmDash ne peut pas restaurer un site, et les migrations du noyau n’ont pas d’étape d’annulation opérationnelle. 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. Créer votre premier site EmDash liste les versions prises en charge.

Mettre à jour les paquets

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

Déployer et vérifier

Déployez le build comme n’importe quelle autre modification. La commande suivante déploie un site Cloudflare ; pour un déploiement Node.js, redémarrez le processus serveur avec le nouveau build.

pnpm wrangler deploy

Avec le mode de migration d’exécution 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, puis vérifier ensuite la base de données déployée, suivez Gérer les migrations de base de données du noyau. Sa commande emdash migrate --check se termine avec un code non nul lorsque la base de données 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, puis téléversez et récupérez un fichier média jetable. Si le site utilise des tâches planifiées ou des plugins en bac à sable, vérifiez aussi ces chemins.

Notes pour des releases spécifiques

La plupart des releases ne demandent 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 conservait auparavant 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 reposant sur une relation, et ses liens vivent en dehors de la table de la collection. La mise à jour lie chaque champ de référence qui nommait une collection cible à une nouvelle relation et y copie comme liens les IDs d’entrée de sa colonne, de sorte que le champ devienne 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é comme interrogeable ou indexé
• 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 d’une 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 seule sélection est partagée par toutes ses traductions, alors que l’ancienne colonne était par locale. Un champ dont les locales divergent 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 les autres — la mise à jour laisse donc le champ tel quel et les deux valeurs lisibles dans la colonne.

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

Un champ non lié continue de se comporter comme avant. Sa colonne contient l’ID de l’entrée, la valeur est enregistrée et chargée, et le champ peut toujours être indexé et utilisé comme filtre de la liste de contenu. Dans l’éditeur d’entrée, il s’affiche comme une zone de texte plutôt que comme 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 s’affiche comme un sélecteur n’a besoin de rien. Pour un champ qui s’affiche encore comme une zone de texte, suivez Lier un champ qui n’a pas de relation, qui crée la relation et y copie comme liens les IDs enregistrés du champ. Sur un site multilingue, décidez vers quelle entrée chaque traduction doit pointer avant de lier, car la liaison conserve une seule sélection pour toutes.

Si le site casse après une mise à jour

• Le build échoue, ou l’une de vos pages génère une erreur à l’exécution : lisez les entrées de release marquées Breaking pour les versions que vous avez sautées et effectuez les modifications qu’elles indiquent.
• Un plugin ne se charge pas : lisez l’entrée de release du plugin lui-même et Mettre à jour les plugins.
• Une erreur nomme une API Astro ou un paquet @astrojs/* : EmDash requiert Astro 6 ou une version ultérieure. 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 paquets 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 de données migrée, arrêtez le trafic et restaurez ensemble la base de données d’avant la mise à jour et l’artefact ; ne restaurez les médias que si la mise à jour les a modifiés.