Mettre à jour EmDash | EmDash CMS Everything

Ce guide est destiné aux opérateurs de sites : les personnes qui exploitent un site construit sur EmDash et souhaitent le mettre à jour vers une version plus récente. Il couvre le package emdash et @emdash-cms/cloudflare. Les packages de plugins ont leur propre guide, Upgrading plugins on your site, et les modifications de vos propres collections et champs sont couvertes dans Evolving a Deployed Site.

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 version corrective, par exemple de 0.35.0 à 0.35.1, apporte des corrections de bugs et de petites améliorations.
Une version 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 requiert de votre part.

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 d’emdash, mettez donc à jour les deux packages en une seule étape. Les packages de plugins comme @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 a une entrée par package 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 la mise à jour

Faites une sauvegarde. Les migrations du noyau qu’une nouvelle version applique à la base de données n’ont pas d’étape d’annulation, donc une sauvegarde est le seul moyen de revenir à l’état précédent. Backups décrit les options 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. Getting Started liste les versions supportées.

Mettre à jour les packages

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.

Vérifiez les versions installées et la dernière release.
```
pnpm outdated emdash @emdash-cms/cloudflare
```
Mettez les deux packages à la dernière release.

Un package.json généré par template liste les packages avec une plage caret comme ^0.35.0. Pour les versions inférieures à 1.0, une plage caret n’admet que les versions correctives (0.35.1, pas 0.36.0), et pnpm up sans options supplémentaires reste dans la plage. Le flag --latest réécrit la plage vers la release la plus récente et l’installe.
```
pnpm up --latest emdash @emdash-cms/cloudflare
```
Ajoutez les packages de plugins de votre package.json à la même commande.
Construisez le site.
```
pnpm build
```
Le build écrit le manifeste de migration pour la version installée. Si le build échoue, voir Si le site ne fonctionne plus après une mise à jour.
Démarrez le site localement et ouvrez l’admin à /_emdash/admin.
```
pnpm dev
```
L’intégration EmDash génère emdash-env.d.ts au démarrage du serveur de développement. Les migrations du noyau en attente s’exécutent à la première requête.

Déployer et vérifier

Déployez le build de la même manière que tout autre changement. 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 à l’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, et pour vérifier la base de données déployée ensuite, suivez Manage Core Database Migrations. Sa commande emdash migrate --check termine avec un code non nul quand 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 et une page publique du site.

Si le site ne fonctionne plus après une mise à jour

Le build échoue, ou 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 changements indiqués.
Un plugin ne se charge pas : lisez l’entrée de release propre au plugin et Upgrading plugins on your site.
Une erreur nomme une API Astro ou un package @astrojs/* : EmDash nécessite Astro 6 ou ultérieur. Le guide de mise à jour d’Astro explique comment mettre à jour astro et ses intégrations officielles ensemble.
Pour revenir à la release précédente, réinstallez les versions précédentes des packages. La réinstallation n’annule pas les migrations du noyau ; si la release précédente échoue contre la base de données migrée, restaurez la sauvegarde prise avant la mise à jour.