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. L’outil de mise à jour couvre chaque dépendance directe emdash et @emdash-cms/* du projet. Les modifications de vos propres collections et champs sont traitées dans Faire évoluer le schéma d’un site déployé.

Compatibilité des releases

EmDash suit le versionnement sémantique :

• Une release de correctif apporte des corrections et de petites améliorations rétrocompatibles.
• Une release mineure apporte des fonctionnalités rétrocompatibles.
• Une release majeure peut exiger des modifications d’un projet existant. Ses entrées de release identifient les projets concernés et les actions requises.

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. upgrade-emdash récupère la plage du changelog de chaque paquet direct à partir de son tag de release GitHub exact. Il supprime les entrées générées de mise à jour de dépendances, conserve intégralement les entrées majeures, mineures et correctives rédigées à la main, et dédoublonne les entrées répétées d’un paquet à l’autre.

Les fichiers de template ne sont pas mis à jour

Créer un site à partir d’un template copie dans votre projet les fichiers du template, comme les layouts, les composants, les styles et astro.config.mjs. L’outil de mise à jour modifie les dépendances EmDash directes et actualise les agent skills d’EmDash. Il laisse les fichiers d’application et de configuration du site au responsable du projet ou à un agent, qui les modifient à partir de l’ordre de travail de la mise à niveau. 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

L’outil de mise à jour modifie les fichiers du projet et les paquets installés sans se connecter à la base de données du site ; il n’exige donc pas de sauvegarde propre à la mise à niveau avant de s’exécuter. Après l’installation, .emdash/UPGRADE.md identifie les éventuelles migrations du noyau ajoutées.

Avant de démarrer ou de déployer l’application mise à niveau, créez un point de récupération lorsque l’ordre de travail liste des migrations ajoutées, que emdash migrate --status signale une migration antérieure en attente, ou qu’une entrée de release exige une action de projet qui modifie des données. Suivez Sauvegardes et récupération pour la base de données configurée. La sauvegarde JSON d’EmDash ne peut pas restaurer un site.

L’outil de mise à jour exige emdash 0.35.0 ou plus récent, la première release qui signale ses migrations du noyau. Pour un site plus ancien, créez un point de récupération, mettez à jour emdash et les autres paquets directs @emdash-cms/* vers la version 0.35.0 avec le gestionnaire de paquets du projet, et passez en revue les changelogs des paquets jusqu’à cette release. Exécutez ensuite l’outil de mise à jour pour le reste de la mise à jour.

L’outil de mise à jour lit les paquets depuis node_modules ; il ne prend donc pas en charge les installations Yarn Plug’n’Play. Pour un projet Yarn qui utilise Plug’n’Play, définissez nodeLinker: node-modules dans .yarnrc.yml et exécutez yarn install avant de lancer l’outil de mise à jour.

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.

Planifier et appliquer la mise à jour

Exécutez l’outil de mise à jour depuis le répertoire du projet du site. Il lit les versions des paquets installés et l’identité des migrations du noyau, puis résout séparément le dist-tag npm choisi pour chaque paquet EmDash direct. Le tag par défaut est latest ; utilisez --to next, --to beta ou un autre dist-tag pour choisir un canal de releases. --to n’accepte pas de version exacte.

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. Un Worker Cloudflare laisse les migrations de contenu volumineuses à emdash migrate et répond par un 503 tant qu’elles ne sont pas appliquées. Ne déployez pas un build comportant des migrations en attente tant que le point de récupération requis n’existe pas. Pour appliquer les migrations 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 modifient des données qu’EmDash stockait déjà, ou qui ne peuvent pas les réparer, 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.

Corrigé : champs de référence recherchables

Dans les versions précédentes, un champ de référence marqué searchable cassait sa collection : en ajouter un à une collection dont la recherche était activée échouait, et après qu’un seed avait activé la recherche, la création ou l’enregistrement de n’importe quelle entrée de cette collection échouait avec no such column dans le journal du serveur.

La recherche du site et la recherche dans la liste de contenu ignorent le drapeau searchable d’un champ de référence lié à une relation. La mise à jour ne répare pas une collection qu’un seed a déjà cassée, car son index de recherche attend toujours le champ.

Que dois-je faire ?

Si la création ou l’enregistrement d’entrées dans une collection échoue et que le journal du serveur affiche no such column, ouvrez la collection sous Content Types, décochez la case Search, puis enregistrez. Cochez ensuite à nouveau Search et enregistrez. Cela reconstruit l’index de recherche de la collection, et la collection accepte de nouveau les entrées nouvelles et modifiées.

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.