Mettre à jour EmDash : versions, ruptures et procédure

EmDash en est à la version 0.34.0, publiée le 18 août 2026, et le dépôt a produit trois versions mineures en trois semaines. Un numéro qui commence par zéro annonce une chose : rien ne garantit qu’une version mineure préserve les interfaces de la précédente. La procédure ci-dessous est celle qui protège un site en service : sauvegarder, lire les notes, monter les paquets, migrer la base comme une étape de déploiement, puis vérifier.

Cet article est vérifié contre la version 0.34.0 au 23 août 2026. Sur un produit qui publie chaque semaine, cette date compte autant que le contenu : revérifiez les numéros de version et les options de commande contre les notes de version de votre propre montée.

Ce que la numérotation vous dit, et ce qu’elle ne dit pas

En versionnage sémantique, un projet en 0.x n’a pas d’engagement de stabilité : la rupture arrive dans la version mineure, pas dans une version majeure annoncée. Les trois dernières livraisons du cœur sont datées du 5, du 11 et du 18 août 2026. À cette cadence, un site laissé six semaines sans montée saute six versions mineures d’un coup, et cumule leurs ruptures.

Le second piège est la structure du dépôt. EmDash est un monorepo — un seul dépôt qui publie plusieurs paquets npm — et ces paquets ne partagent pas tous la même ligne de version. Le cœur et ses satellites avancent ensemble, d’autres suivent leur propre rythme.

Paquet	Version au 18 août 2026
emdash	0.34.0
@emdash-cms/admin, auth, blocks, cloudflare, x402	0.34.0
create-emdash	0.34.0
@emdash-cms/plugin-cli	0.8.1
@emdash-cms/sandbox-workerd	0.5.0
@emdash-cms/plugin-forms	0.2.5
@emdash-cms/auth-atproto	0.2.34

La conséquence est pratique : vous ne pouvez pas déduire la version d’un paquet de celle du cœur. Une extension bloquée en 0.2.x n’est pas en retard pour autant, et un pnpm up qui n’aligne que emdash laisse le reste derrière. Listez explicitement chaque paquet EmDash de votre package.json dans la commande de montée.

Avant de toucher à quoi que ce soit

Trois précautions, dans cet ordre. Elles prennent quelques minutes et sont ce qui distingue une montée réversible d’une montée définitive.

1. Une sauvegarde téléchargée. Dans l’administration, Réglages → Sauvegardes, le bouton de téléchargement produit une archive JSON du contenu, du modèle de contenu, des taxonomies, des menus et des réglages. La documentation la présente explicitement comme l’outil des opérations risquées, et une montée de version en est une.
2. Le point de restauration de la base. Sur Cloudflare D1, relevez le repère avant l’opération : npx wrangler d1 time-travel info ma-base. Sur une installation Node avec SQLite, copiez le fichier de base à l’arrêt, ou à chaud avec sqlite3 emdash.db ".backup sauvegarde.db".
3. Les notes de version. Chaque version du cœur est publiée avec ses changements détaillés, numéro de proposition de fusion à l’appui. Lisez celles de toutes les versions que vous sautez, pas seulement de la cible.

Ce que la sauvegarde JSON ne contient pas mérite d’être su avant d’en avoir besoin : ni les comptes et les clés d’accès, ni les secrets, ni les fichiers médias eux-mêmes — seules leurs métadonnées. Le détail de ces trois exclusions et la façon de les couvrir sont traités dans notre guide dédié à la sauvegarde et à la restauration d’un site EmDash.

Monter les paquets

La montée elle-même tient en deux commandes, lancées à la racine du projet du site :

pnpm up emdash @emdash-cms/admin @emdash-cms/auth @emdash-cms/plugin-webhook-notifier
pnpm build

Adaptez la liste à vos dépendances réelles. Si la construction passe et que le site démarre, il n’y a rien d’autre à faire. Si elle échoue, l’erreur pointe presque toujours vers une rupture documentée dans les notes de version : c’est là qu’il faut chercher, avant de modifier du code au hasard.

Faites cette montée sur un environnement de test avant la production. Sur une installation Cloudflare, un environnement Wrangler distinct avec sa propre base D1 suffit ; sur une installation Node, une copie du conteneur et une copie du fichier SQLite. Le point n’est pas théorique : les migrations du cœur modifient le schéma, et une migration appliquée ne se défait pas.

Migrer la base sans laisser le hasard décider

Par défaut, EmDash applique ses migrations internes au démarrage, à la première requête après le déploiement. C’est commode en développement et risqué en production : le nouveau code reçoit du trafic pendant que la base change encore.

La procédure de déploiement inverse l’ordre. La construction Astro écrit un manifeste .emdash/migrations.json qui enregistre la version exacte, l’ensemble ordonné des migrations et l’exécuteur de l’adaptateur. On migre avec ce manifeste, puis on déploie le même artefact.

pnpm build
pnpm emdash migrate --status
pnpm emdash migrate
pnpm wrangler deploy
pnpm emdash migrate --check

--status rapporte les migrations appliquées, en attente et inconnues sans rien modifier. La commande nue affiche la cible et demande confirmation : relisez le nom du compte et de la base à cette invite, c’est le dernier garde-fou avant d’écrire dans la mauvaise base. --check n’applique rien et sort en erreur s’il reste des migrations en attente.

Le mode d’exécution se règle dans la configuration de l’intégration, et il se durcit progressivement :

Mode	Comportement au démarrage
auto	Applique les migrations en attente. Valeur par défaut, compatible avec l’existant.
check	Vérifie et répond 503 tant que des migrations connues sont en attente.
manual	Ne vérifie ni n’applique rien. À réserver aux déploiements qui migrent et vérifient à chaque fois.

La progression raisonnable est auto pendant qu’on met en place l’étape de déploiement, check quand elle est fiable, manual seulement quand une vérification externe est imposée à chaque livraison. Ajoutez .emdash/migrations.json à votre .gitignore : il est produit et consommé par l’espace de travail de construction, il n’a rien à faire dans le code source.

Ce qui casse en pratique

Les ruptures observées dans les notes de version récentes donnent une bonne idée des familles de problèmes à attendre. Trois cas concrets, tirés de la 0.34.0 et de la documentation de montée des extensions.

Les extensions tierces qui n’ont pas suivi. Les extensions maison d’EmDash sont passées d’un export nommé appelé comme une fabrique à un export par défaut que l’on passe directement dans la configuration. Une extension tierce qui expose encore l’ancienne forme n’a pas été mise à jour pour cette version : la configuration par appel a disparu au profit de l’écran de réglages de l’extension dans l’administration. C’est le motif le plus fréquent d’échec de chargement après une montée, et il ne se règle pas de votre côté.

Les types régénérés. La génération de types produit désormais des types précis pour les champs répétables, là où elle émettait un type inconnu. Du code qui déclarait à la main la forme d’une ligne et la forçait par conversion peut signaler des erreurs après la montée, parce que ce type avait divergé du schéma. Régénérez les types puis corrigez les écarts : ce sont des bogues révélés, pas créés.

Les contraintes de contenu qui se resserrent. La même version rend le slug obligatoire pour les entrées publiées des collections adressables, et introduit une option pour déclarer non adressable une collection qui ne sert qu’à du contenu référencé. Une base qui contenait des entrées publiées sans slug doit être corrigée, pas contournée.

À cela s’ajoute une règle d’architecture que la documentation formule clairement : les migrations du cœur suivent un séquencement en trois temps — étendre, déployer, contracter. Pendant un déploiement progressif, l’ancien et le nouveau code peuvent tourner en même temps sur une base déjà étendue. Ne contractez jamais un schéma tant qu’une version déployée s’en sert encore.

Le retour arrière, préparé avant

Un retour arrière ne s’improvise pas après l’incident, parce que la base a déjà changé. Deux moyens, selon l’hébergement.

Sur Cloudflare D1, la restauration à un instant donné est toujours active et ne demande aucune configuration : npx wrangler d1 time-travel restore ma-base --timestamp=2026-08-23T13:00:00Z. L’historique couvre 30 jours sur le plan payant, 7 jours sur le plan gratuit, avec une granularité à la minute. Elle restaure toute la base — contenu, comptes, réglages —, ce qui en fait l’outil des incidents, pas celui des corrections ponctuelles.

Sur Node, le retour arrière est la copie de base prise avant l’opération, plus le redéploiement de l’image précédente. C’est plus manuel et parfaitement fiable, à condition que la copie existe. C’est aussi l’argument principal pour garder l’artefact de la version précédente prêt à redéployer : la mise en production d’EmDash se juge autant sur la sortie de secours que sur le déploiement lui-même.

Une dernière précaution vaut pour les deux : la restauration d’une base ne remet pas en place les fichiers médias, qui vivent dans le stockage objet. Si la montée a touché aux médias, les deux restaurations sont à mener ensemble.

Une cadence tenable pour un site en service

Sur un produit qui publie chaque semaine, suivre chaque version est un travail à part entière et sauter six mois est un mur. Le compromis qui tient : monter toutes les deux à quatre semaines, en environnement de test d’abord, avec les notes de version lues et une sauvegarde téléchargée. C’est assez fréquent pour n’affronter qu’une ou deux ruptures à la fois, assez espacé pour ne pas y passer ses journées.

Deux réflexes complètent la procédure. Épinglez vos versions dans le fichier de verrouillage et livrez ce fichier, pour que l’environnement de test et la production installent exactement les mêmes paquets. Et gardez, dans votre propre dépôt, une note datée de la version en service : c’est l’information qui manque toujours au moment d’un incident. Pour le reste des commandes disponibles, l’interface en ligne de commande d’EmDash est le point de départ.

Questions fréquentes

EmDash étant en version 0.x, peut-on sauter plusieurs versions d’un coup ?

Techniquement oui, la montée applique les migrations en attente dans l’ordre. En pratique vous cumulez les ruptures de toutes les versions sautées, sans savoir laquelle a cassé la construction. Montez par paliers si vous avez plusieurs versions de retard, en vérifiant que le site démarre entre chacun.

Faut-il mettre à jour tous les paquets EmDash ensemble ?

Le cœur et ses satellites — administration, authentification, blocs, adaptateur Cloudflare — partagent la même ligne de version et se montent ensemble. Les extensions et l’outillage suivent leur propre numérotation et peuvent rester en arrière sans que ce soit anormal. Listez chaque paquet explicitement dans la commande plutôt que de compter sur une montée globale.

Que faire si une extension tierce ne charge plus après la montée ?

Vérifiez d’abord sa forme d’export : les extensions maison sont passées à un export par défaut sans appel de fabrique, et une extension restée à l’ancienne forme n’a pas été adaptée à la version. Consultez son journal des changements ; s’il n’existe pas de version compatible, le choix est de la retirer ou de rester à la version précédente d’EmDash.

Les migrations peuvent-elles s’appliquer toutes seules en production ?

Oui, c’est le comportement par défaut : le mode auto applique les migrations en attente au démarrage. Sur un site en service, préférez appliquer les migrations depuis le manifeste de construction avant le déploiement, puis passer le mode d’exécution à check pour qu’une requête ne soit jamais servie sur un schéma en retard.