Livre de procédure de version

Processus manuel provisoire. Ce runbook explique comment publier une version stable aujourd’hui en utilisant release-stable-manual.yml. Il reste le processus en vigueur jusqu’à ce que release-plz soit déployé et le remplace ; cette migration n’a pas encore eu lieu (voir Où cela nous mène).

Si quelque chose ici vous semble lourd, il s’agit d’une friction intentionnelle : nous n’avons pas encore la discipline d’automatisation nécessaire pour la supprimer en toute sécurité.

Dernière vérification effectuée pour le cycle de version v0.8.2.

Le processus en sept étapes

1. Générer CHANGELOG-next.md en utilisant le skill changelog
2. Ouvrir et fusionner une PR d’incrémentation de version
3. Simuler les workflows de release localement avec act
4. Déclencher le workflow Release Stable via un déclenchement manuel
5. Approuvez les deux portes d’environnement lorsque vous y êtes invité
6. Vérifier que la version existe et que les assets sont téléchargeables
7. Déploiement de la documentation versionnée

C’est l’ensemble du processus. Tout le reste (crates.io, Docker, redéploiement du site web, Scoop, AUR, Discord, tweet) s’exécute automatiquement en tant que tâches en aval. Homebrew Core détecte la version stable de GitHub grâce à son propre service d’autobump. Vous n’avez rien à faire pour ces éléments, sauf si une tâche échoue explicitement ou si la mise à jour externe de Homebrew reste obsolète.

Étape 1 : Générer CHANGELOG-next.md

Exécutez le skill changelog-generation pour produire CHANGELOG-next.md. Sa procédure complète se trouve dans .claude/skills/changelog-generation/SKILL.md.

Le skill génère le changelog à partir du git log entre le dernier tag stable et HEAD, résout les contributeurs via GitHub GraphQL et écrit le fichier. Validez le résultat directement dans une branche éphémère et incluez-le dans la PR d’incrémentation de version (étape 2), ou ouvrez-le comme une PR distincte précédente si le diff est volumineux.

Si CHANGELOG-next.md existe déjà à la suite d’un cycle de publication précédemment interrompu, vérifiez son exactitude avant de le réutiliser.

Étape 2 : Incrémenter la version et fusionner la PR de version

Mettez à jour workspace.package.version dans le Cargo.toml de l’espace de travail, puis exécutez les deux scripts de publication dans l’ordre. Commencez par synchroniser chaque référence de version dans l’ensemble du dépôt :

./scripts/release/bump-version.sh    # version de Cargo.toml

Cette mise à jour modifie les badges du README, la configuration de Tauri et les exemples de description des workflows, puis régénère toutes les surfaces d’installation pilotées par la spécification via cargo generate installers : install.sh, setup.bat, dist/aur/PKGBUILD, dist/aur/.SRCINFO, dist/scoop/zeroclaw.json, flake.nix, les ensembles de fonctionnalités du Dockerfile/Containerfile, dev/ci/docker-tags.toml, docs/book/src/_snippets/install.md, les blocs de chemin rapide Unix dans le README et la documentation des plateformes, ainsi que le bloc des binaires précompilés Windows dans docs/book/src/setup/windows.md. Les valeurs de version, de fonctionnalités et de paquetage de l’application proviennent de Cargo.toml et de [package.metadata.zeroclaw] ; les quatre voies d’installation stables proviennent de contrats typés dans xtask/src/generate/spec.rs. Cette mise à jour maintient automatiquement la cohérence de ces surfaces ; ne modifiez donc jamais manuellement une région générée. La disponibilité effective des versions reste rédigée manuellement et n’est pas déduite par le générateur. Ce script actualise également les hachages des dépendances Git de Nix (nix/hashes.json) via scripts/dev/refresh-nix-hashes.sh.

Actualiser et épingler les traductions

Une fois que bump-version.sh a défini la version de publication, actualisez les catalogues de traduction de la documentation et épinglez-les au tag correspondant. Si les catalogues ont été préparés séparément, inspectez la couverture et validez-les avant de créer le tag :

cargo mdbook stats
cargo mdbook check

Exécutez ensuite le wrapper de publication :

./scripts/release/refresh-translations.sh --model-provider anthropic.release

refresh-translations.sh lit la version depuis Cargo.toml (rien n’est saisi à la main), exécute la passe de traduction, valide et pousse les catalogues vers le sous-module zeroclaw-labs/zeroclaw-docs-translations, y crée le tag v{version}, puis prépare le gitlink du dépôt principal épinglé sur ce tag. Il initialise le sous-module s’il n’est pas déjà extrait. Exécutez-le après bump-version.sh pour que la version de Cargo.toml qu’il lit soit celle de la release. L’alias du fournisseur configuré doit être fourni explicitement afin que la release ne dépende pas d’un backend codé en dur ; passez --config-dir si nécessaire. L’alias sélectionné par --model-provider est résolu depuis providers.models.<kind>.<alias>. Utilisez --no-translate lorsque les catalogues sont déjà à jour, ou passez une version explicite avant --model-provider pour remplacer la valeur par défaut de Cargo.toml, par exemple :

./scripts/release/refresh-translations.sh 0.8.2 --model-provider anthropic.release

Valider tout ensemble :

chore: bump version to vX.Y.Z

Si la PR modifie également [workspace.package] rust-version ou les toolchains Rust verrouillées, traitez-la comme une modification de compatibilité et non comme une simple infrastructure de publication. La PR doit indiquer le nouveau MSRV, expliquer le parcours de mise à niveau des builds à partir des sources, et démontrer que la CI, Docker, l’installateur et les surfaces générées sont cohérents avec ce nouveau minimum avant la fusion.

Ouvrez une PR. Ajoutez-lui les libellés type:ci, size:XS et tous les libellés de chemin ajoutés par l’outil d’étiquetage des PR. Si la PR relève le niveau minimal de la chaîne d’outils, appliquez également risk:high et faites-la passer par la voie D. Obtenez deux approbations indépendantes de la Core Team. Ne fusionnez que lorsque la CI est au vert. Le contrôle Installer Drift de la CI fait échouer la PR si une surface générée n’est pas synchronisée avec la spécification, de sorte qu’une régénération oubliée ne puisse pas être fusionnée. Le contrôle Validate Translations Pin positionne le sous-module sur le commit épinglé et valide le format du catalogue ainsi que la parité des msgid, de sorte qu’un mauvais épinglage ne puisse pas non plus être fusionné. Consultez Documentation et traductions pour plus de détails sur le pipeline de traduction.

Vérifiez que la fusion s’est déroulée correctement :

git fetch origin
git show origin/master:Cargo.toml | grep '^version'
# Doit afficher : version = "X.Y.Z"

Étape 3 : Effectuez une exécution à blanc des workflows de release en local avec act

Le workflow Release Stable est un graphe de jobs GitHub Actions qui consomme votre fenêtre d’approbation de la barrière d’environnement dès l’instant où vous cliquez sur Run workflow. Si une étape du workflow est défectueuse : un artefact de build manquant, un chemin obsolète, une étape de codegen que quelqu’un a supprimée sans mettre à jour la CI, l’échec apparaît après que vous vous êtes engagé dans une fenêtre de publication, avec la PR de version déjà fusionnée et master à la nouvelle version. La récupération implique de faire atterrir une branche de correctif d’urgence, de relancer la CI et de livrer sous pression temporelle sur un arbre qui se présente déjà comme une version entièrement publiée.

L’assurance à moindre coût contre cela consiste à exécuter d’abord le même graphe de jobs en local, sur le commit master fusionné exact, avant d’ouvrir le formulaire GitHub Actions. act exécute les workflows GitHub Actions dans des conteneurs Docker en utilisant le même écosystème actions/* que GitHub. Il ne reproduit pas parfaitement le runner cloud ; il ne peut pas accéder au runtime d’upload d’artefacts, aux tokens OIDC émis par GitHub, aux secrets d’environnement, ni aux jobs qui dépendent d’un vrai tag de release, mais il exécute bien les étapes de build et de test qui représentent la quasi-totalité des échecs de CI au moment des releases que nous ayons jamais rencontrés.

Cette étape représente un investissement de 15 à 20 minutes par version. Elle a permis de détecter de vrais défauts que la CI habituelle par PR ne révélait pas (car le workflow défaillant ne s’exécute que sur workflow_dispatch, pas sur push).

Configuration unique

act exécute les workflows. La méthode d’installation la plus simple est l’extension GitHub CLI, car elle hérite de votre authentification gh et expose un véritable GITHUB_TOKEN à chaque exécution de workflow :

1. Installez la CLI GitHub depuis https://cli.github.com (Linux, macOS, Windows). Authentifiez-vous une seule fois : gh auth login.

2. Installez l’extension act :

   sh

   gh extension install nektos/gh-act
   

   Les tâches produisant des artefacts ont besoin du protocole du service d’artefacts de act requis par actions/upload-artifact v7 et actions/download-artifact v8, et aucune version actuellement publiée de act ne l’implémente (vérifié jusqu’à la dernière version publiée à la date de rédaction). L’assistant vérifie au préalable la version installée de act avant de démarrer une tâche qui utilise les actions d’artefacts épinglées et s’arrête en cas d’échec : il ne tentera pas d’exécuter la tâche avec une version non vérifiée. Tant qu’une version compatible de act n’est pas publiée et vérifiée au moyen d’un véritable aller-retour d’artefact, utilisez la solution de secours hébergée par GitHub ci-dessous pour toute tâche qui produit ou consomme des artefacts ; c’est la voie recommandée aujourd’hui, et non une rare exception.

3. Installez Docker Engine ou Docker Desktop depuis https://docs.docker.com/engine/install/. Sous Linux, ajoutez-vous au groupe docker afin de ne pas avoir besoin de sudo. act fonctionne également avec Podman et Colima ; consultez la documentation des runners act.

C’est toute la configuration. Les fichiers .actrc et scripts/dev/act-local.sh du dépôt gèrent tout le reste (image du runner, fichier de secrets, serveur d’artefacts, pré-récupération des SHA d’action).

Simulation par version

Assurez-vous que votre arborescence de travail correspond au sommet de la branche master fusionnée de l’étape 2 :

git fetch upstream
git checkout upstream/master

Liste ce qui est exécutable dans chaque fichier de workflow :

./scripts/dev/act-local.sh --list

Exécuter une tâche spécifique, choisir de manière interactive ou exécuter toutes les tâches compatibles avec le mode simulation :

./scripts/dev/act-local.sh release-stable-manual:web   # une tâche
./scripts/dev/act-local.sh                              # sélecteur interactif
./scripts/dev/act-local.sh --all                        # tout job sans risque en simulation (dry-run-safe)

La première exécution télécharge l’image du runner (~1,5 Go) et amorce le cache de compilation Rust via Swatinem/rust-cache ; les exécutions suivantes sont beaucoup plus rapides. Le script crée automatiquement le fichier .secrets (ignoré par git), pré-récupère chaque SHA d’action épinglé dans ~/.cache/act/ (le clone superficiel d’act ne peut pas résoudre des commits arbitraires autrement), transmet GITHUB_TOKEN depuis votre authentification gh vers l’exécution via l’environnement du processus parent (la valeur du token n’apparaît jamais dans argv), et définit --artifact-server-path pour que actions/upload-artifact et actions/download-artifact fonctionnent entre les jobs. Tout cela n’est que du act standard en dessous ; le script supprime simplement la soupe de flags.

Avant le démarrage de toute tâche qui produit ou consomme des artefacts, l’outil auxiliaire vérifie la version résolue de act autonome ou de gh act par rapport à un seuil interne de compatibilité (act >= une valeur sentinelle inatteignable, actuellement 999.0.0). Ce seuil n’est pas une version à installer avec go install ; aucune version publiée de act ne le respecte, et il ne passe à une version réelle et précise qu’une fois qu’un véritable aller-retour d’artefacts a été vérifié avec cette version. Toutes les versions actuellement publiées de act échouent à la vérification préalable avant le début de la compilation et orientent vers les Actions hébergées par GitHub ; ne rétrogradez pas les actions d’artefacts épinglées pour faire réussir un exécuteur local.

Pour --all, la compatibilité est vérifiée sur l’ensemble complet des tâches sélectionnées avant le démarrage de la première tâche. Si une tâche sélectionnée a besoin du service d’artefacts, l’exécution globale échoue par défaut (aucune version actuellement publiée du projet act ne franchit le seuil) et se termine sans exécuter de sous-ensemble partiel. --all --no-allowlist suit la même politique de compatibilité.

Les échecs des vérifications préalables des artefacts sont attendus avec toutes les versions actuellement publiées de act, et ne constituent pas un incident occasionnel. Poussez le commit exact vers GitHub et utilisez le workflow hébergé comme solution de validation de repli pour les tâches produisant des artefacts. La compilation multiplateforme en lecture seule peut être déclenchée en toute sécurité et suivie depuis la CLI :

gh workflow run cross-platform-build-manual.yml --ref <validation-branch>
gh run list --workflow cross-platform-build-manual.yml --branch <validation-branch> --limit 1
gh run watch <run-id> --exit-status

Ne déclenchez pas release-stable-manual.yml prématurément comme substitut à une exécution à blanc : ce workflow publie après les approbations de son environnement. Consignez les tâches locales de génération d’artefacts comme ignorées en raison de la politique de version, utilisez la compilation multiplateforme hébergée pour l’aller-retour des artefacts et réservez l’exécution protégée de stable-release pour l’étape 4.

--all exécute uniquement les tâches figurant sur une liste d’autorisation sûre en mode dry-run

act ne respecte pas les barrières de protection d’environnement de GitHub. Avec le véritable GITHUB_TOKEN du mainteneur injecté dans l’exécution, une invocation locale réussie d’un job qui écrit sur GitHub (un publish qui appelle gh release create, un job docker qui pousse vers GHCR, un docs-deploy qui force-push gh-pages, un daily-audit qui ouvre une issue, un tweet-release ou discord-release qui poste vers un webhook) pourrait produire l’effet de bord réel dès la première tentative.

--all applique donc une liste d’autorisation codée en dur de jobs dont l’exécution locale est avérée sûre ; actuellement les étapes de build produisant uniquement des artefacts dans release-stable-manual.yml et cross-platform-build-manual.yml (validate, web, release-notes, build, build-desktop). Tout le reste est ignoré avec une raison consignée dans les logs :

==> skip release-stable-manual:publish (not on dry-run-safe allowlist)
==> skip release-stable-manual:docker (not on dry-run-safe allowlist)
==> skip release-stable-manual:crates (not on dry-run-safe allowlist)
==> skip release-stable-manual:redeploy-website (not on dry-run-safe allowlist)
==> skip docs-deploy:deploy (not on dry-run-safe allowlist)
==> skip daily-audit:advisories (not on dry-run-safe allowlist)
==> skip tweet-release:tweet (not on dry-run-safe allowlist)

La liste d’autorisation est fail-closed (fermée par défaut) : un nouveau workflow ajouté au dépôt est traité comme potentiellement mutateur jusqu’à ce qu’un mainteneur l’examine et ajoute les identifiants de jobs sûrs à DRY_RUN_SAFE_JOBS dans scripts/dev/act-local.sh. C’est important car discover_jobs parcourt tous les fichiers .github/workflows/*.yml, et pas seulement les workflows de release, une liste de blocage laisserait silencieusement passer un futur workflow avec surface d’écriture.

Deux solutions de contournement existent pour le cas rare où vous avez une raison de tenter d’exécuter localement un job qui ne figure pas dans la liste d’autorisation :

• ./scripts/dev/act-local.sh release-stable-manual:publish : la forme explicite <wf>:<job> exécute ce que vous demandez et affiche un avertissement bien visible avant d’invoquer act si la cible ne figure pas dans la liste d’autorisation.
• ./scripts/dev/act-local.sh --all --no-allowlist : désactive le filtre de liste d’autorisation pour l’ensemble d’une exécution --all (à utiliser uniquement lorsque vous avez déjà vérifié que les étapes du workflow n’atteindront pas une surface de mutation, par exemple sur un fork sans véritables identifiants de registre et avec un fichier .secrets vide).

Ce qui est censé échouer sous act (et c’est normal)

act ne peut pas simuler quelques fonctionnalités spécifiques à GitHub. Ces échecs ne sont pas de véritables défauts :

• Jobs qui dépendent d’un véritable tag de release (publish créant une GitHub Release).
• Tâches nécessitant une validation d’environnement (publish, docker et le publisher de crates) : l’interface d’approbation n’existe pas en local.
• Jetons d’identité fédérée basés sur OIDC.

Tout le reste, une erreur tsc, un fichier manquant, un échec de compilation Rust, une incohérence du fichier de verrouillage cargo, est un défaut réel. Ne cliquez pas sur Run workflow dans le formulaire GitHub Actions tant que ces problèmes ne sont pas corrigés via une PR standard à partir de master.

Étape 4 : Déclencher la publication

Aller à :

https://github.com/zeroclaw-labs/zeroclaw/actions/workflows/release-stable-manual.ymlCliquez sur Run workflow. Renseignez :

• Branch : master
• Version stable à publier : X.Y.Z, sans préfixe v

Cliquez sur Run workflow.

Le premier job (validate) vérifie que la version correspond à Cargo.toml et qu’aucun tag vX.Y.Z n’existe déjà. En cas d’échec, corrigez l’incohérence et relancez. N’essayez pas de le contourner.

Étape 5 : Approuver les portes d’environnement

Trois tâches sont soumises aux règles de protection des environnements GitHub. Lorsque chacune est en attente, vous verrez une bannière “Waiting for review” dans l’exécution du workflow.

Approuvez les trois lorsqu’ils apparaissent. N’approuvez crates-io qu’une fois que le contrôle préalable de son paquet sans jeton est réussi :

Si vous manquez la fenêtre d’approbation et qu’une tâche expire, relancez uniquement la tâche échouée depuis la page d’exécution du workflow ; vous n’avez pas besoin de tout recommencer depuis le début.

Étape 6 : Vérifier la version publiée

Une fois publish terminé, confirmez :

[ ] GitHub Release exists at /releases/tag/vX.Y.Z and is marked Latest
[ ] Release notes are non-empty
[ ] SHA256SUMS asset is present and non-empty
[ ] Both SPDX and CycloneDX SBOM assets are present
[ ] Exactly one zeroclaw-vX.Y.Z-verification.tar.gz asset is present
[ ] No loose *.bundle, *.attestation.jsonl, or *.intoto.jsonl assets are present
[ ] At least one binary archive is downloadable (spot-check linux x86_64)
[ ] Prebuilt Docker and generated Docker matrix jobs are green

CHANGELOG-next.md est intentionnellement conservé sur master après la publication : le job de publication se contente de le lire comme corps de la release, il ne le supprime pas. Le cycle de publication suivant l’écrase, donc aucun nettoyage manuel n’est nécessaire.

Pour le chemin normal workflow_dispatch, Docker Publish s’exécute de manière synchrone au sein du workflow de publication stable. Vous n’avez pas besoin d’une vérification Docker distincte si tous les jobs de publication sont au vert. Si un mainteneur démarre plutôt la publication en poussant un tag vX.Y.Z, Docker Publish démarre en tant qu’exécution distincte déclenchée par le tag ; confirmez que cette exécution associée est au vert avant de considérer la publication du conteneur comme terminée. crates.io, Scoop et AUR ne nécessitent une attention distincte que lorsque leurs jobs sont en échec. Homebrew Core est externe à ce workflow ; son service d’autobump vérifie les formules éligibles selon son propre calendrier.

Les utilisateurs qui souhaitent vérifier les signatures, les SBOM ou la provenance SLSA sur les artefacts publiés peuvent consulter Vérification des artefacts de publication.

Après toute modification du workflow release-attestation, un mainteneur doit également exécuter la répétition de vérification en ligne et hors connexion décrite dans docs/maintainers/release-attestation-runbook.md avant de clôturer le ticket de suivi. Une vérification locale du workflow ou une exécution de act ne remplace pas ce contrôle au niveau de la release, car ni l’une ni l’autre ne peut émettre l’attestation OIDC de production de GitHub.

Étape 7 : Déploiement de la documentation versionnée

La documentation ZeroClaw utilise une structure versionnée sur la branche gh-pages. Le job deploy-docs du workflow Release Stable déclenche le workflow Deploy mdBook docs to Pages pour le tag de version une fois que publish a réussi ; cette exécution déclenchée construit et publie la documentation de la version dans /vX.Y.Z/ de manière asynchrone (le job de déclenchement n’attend pas la fin). Les détails d’amorçage et de version plancher ci-dessous sont des informations de référence pour les cas où vous devez recréer gh-pages ou modifier la fenêtre des versions prises en charge.

Pourquoi un déclenchement explicite et non le déclencheur de push de tag. docs-deploy.yml répertorie tags: [v*], mais le tag de release est créé par le job publish via gh release create en utilisant GITHUB_TOKEN. GitHub ne démarre pas une nouvelle exécution de workflow à partir d’un push de tag créé avec GITHUB_TOKEN (docs), de sorte que le déclencheur tags: [v*] ne se déclenche jamais pour une release effectuée de cette manière. Le job deploy-docs invoque donc docs-deploy.yml via workflow_dispatch (l’exception documentée qui s’exécute même sous GITHUB_TOKEN) avec le tag en entrée. Si vous créez un jour un tag à la main avec un token personnel à la place, le déclencheur de push tags: [v*] se déclenche et le déclenchement du workflow de release devient une réexécution sans effet du même déploiement, et les deux chemins convergent vers /vX.Y.Z/.

Ce qui se passe automatiquement

• Le job deploy-docs déclenche un build dont le résultat est déposé dans /vX.Y.Z/.
• « Stable » est un pointeur, pas une copie. C’est le déploiement du tag de release (par ex. v0.8.0) qui construit et publie le répertoire de docs de cette version. bump-version.sh écrit la version publiée dans docs/book/stable-version.txt ; intégrer ce changement sur master rafraîchit uniquement les métadonnées stable. Le déploiement de master ne reconstruit ni ne republie les docs du tag de release ; il copie stable-version.txt à la racine gh-pages et régénère la redirection racine / ainsi que l’entrée « Stable (latest release) » du sélecteur de version, afin que les deux pointent vers le répertoire de version déjà publié de cette release. Le déploiement échoue de manière explicite si le répertoire de version nommé n’est pas présent sur gh-pages. Il n’y a pas d’arborescence /stable/ en double.
• L’ordre est important : le déploiement du tag doit placer /vX.Y.Z/ sur gh-pages avant qu’un déploiement master puisse basculer le pointeur stable vers celui-ci. Dans la séquence de publication normale, la PR de mise à jour de version fusionne en premier (étape 2), donc son déploiement de docs master s’exécute généralement avant que Release Stable crée et déploie le tag. Ce déploiement master antérieur constate l’absence de /vX.Y.Z/ et conserve délibérément le pointeur précédent ; le basculement est différé (voir la logique de basculement différé dans docs-deploy.yml). Le job deploy-docs crée ensuite /vX.Y.Z/, et le basculement est publié lors du prochain déploiement master après que le répertoire est en ligne. Notez que deploy-docs se contente de déclencher la compilation du tag et n’attend pas sa fin : un job deploy-docs au vert signifie que le déclenchement a été accepté, pas que l’exécution des docs est terminée. Une fois /vX.Y.Z/ en ligne, déclenchez docs-deploy.yml avec tag=master pour publier le basculement du pointeur stable (et vérifiez que les exécutions déclenchées ont bien réussi dans l’onglet Actions).
• gh-pages est éphémère : chaque déploiement effectue un force-push d’un unique commit orphelin (sans historique cumulé) et applique la rétention via DOCS_KEEP_VERSIONS (master plus les N versions finales les plus récentes ; les pré-versions et les anciennes versions finales sont élaguées). Cela permet de limiter la taille du clone.
• Le répertoire _shared/ (contenant les CSS de l’interface, les JS et les favicons) est mis à jour à partir du build afin que le thème se propage à toutes les versions déployées.
• Les locales traduites (es, fr, ja, zh-CN) sont rendues à partir du sous-module docs/book/po, que le déploiement résout via submodules: recursive au commit épinglé par la référence déployée. Cet épinglage est défini lors du bump de version ; voir Étape 2 pour la procédure de rafraîchissement, de tag et d’épinglage. L’anglais n’a pas besoin de sous-module.

Amorçage de gh-pages

Si gh-pages est un jour supprimée ou doit être entièrement recréée, initialisez les versions dans cet ordre précis :

1. Version la plus ancienne prise en charge : workflow_dispatch avec le tag v0.7.5
2. Prochaines versions : workflow_dispatch avec le tag v0.8.0-beta-1, etc.
3. Master actuel : workflow_dispatch avec le tag master

[!IMPORTANT] master doit être déployé en dernier lors du bootstrapping. Il écrit la couche de chrome _shared/ définitive utilisée par toutes les autres versions.

[!NOTE] La version stable est résolue depuis docs/book/stable-version.txt (validé dans le code source, publié à la racine gh-pages sous stable-version.txt). Après l’amorçage, vérifiez que ce fichier référence bien la version GA prévue ; la redirection à la racine et l’entrée du sélecteur « Stable (latest release) » s’appuient dessus. Aucun répertoire /stable/ n’est créé.

Redéploiements manuels et le plancher de version

Pour redéployer manuellement une version spécifique :

1. Allez dans Actions → Deploy mdBook docs to Pages
2. Cliquez sur Run workflow
3. Entrez le tag (par exemple, v0.7.5 ou master)

Le plancher DOCS_MIN_VERSION : Pour éviter de déployer accidentellement des versions très anciennes ou non prises en charge, le workflow applique un plancher de version minimale (actuellement v0.7.5).

• Les tags plus anciens que DOCS_MIN_VERSION (comme v0.7.4) sont rejetés par le workflow.
• cargo mdbook gen-versions (l’assistant xtask) ignore tous les répertoires sur gh-pages situés en dessous de ce seuil, les excluant ainsi du menu déroulant des versions.

Si vous devez relever le seuil minimal pour abandonner la prise en charge d’une version plus ancienne :

1. Mettez à jour la variable d’environnement DOCS_MIN_VERSION dans .github/workflows/docs-deploy.yml.
2. Les répertoires des anciennes versions sont automatiquement supprimés lors du prochain déploiement par la passe de rétention DOCS_KEEP_VERSIONS ; aucune modification manuelle de gh-pages n’est requise pour libérer de l’espace.

Si quelque chose ne va pas

L’exécution s’arrête instantanément avec startup_failure (aucun job créé) : Considérez cela comme un symptôme, et non comme un diagnostic de liste d’autorisation. Vérifiez le résumé de l’exécution et la politique Actions du dépôt. Si GitHub signale un rejet lié aux actions sélectionnées et que le workflow de publication a récemment ajouté ou modifié des références uses:, comparez ces références à Actions autorisées. Ajoutez uniquement le motif rejeté dans Paramètres → Actions → Général, attendez quelques minutes que le paramètre se propage, puis déclenchez une nouvelle exécution. Si GitHub ne signale pas de rejet lié à une politique, examinez plutôt la définition du workflow ou une autre politique du dépôt.

échec de la validation : incompatibilité de version : La PR de montée de version n’a pas été fusionnée, ou vous avez saisi une version incorrecte. Corrigez l’incompatibilité et relancez le déclenchement.

Délai d’attente dépassé pour une barrière d’environnement : Relancez uniquement la tâche en échec. Inutile de redémarrer le workflow.

Échec d’une tâche de distribution Scoop ou AUR : chacune dispose d’un sous-workflow correspondant déclenchable manuellement. Réexécutez d’abord le sous-workflow concerné avec dry_run: true pour confirmer la correction, puis avec dry_run: false. Ces tâches sont facultatives : l’échec d’une tâche de distribution n’invalide pas la publication elle-même. En cas d’échec des identifiants Scoop, utilisez Scoop Bucket Canary au lieu de considérer une exécution à blanc générique comme une preuve de validité des identifiants ; le canary active le chemin credential_canary avec un comportement de refus par défaut.

Le système de publication de crates.io s’est arrêté après avoir publié certains crates : N’incrémentez pas la version et ne lancez pas une deuxième release. Les versions de crates.io ne peuvent être ni remplacées ni supprimées. Corrigez le crate défaillant sur le même commit de release, puis relancez Pub crates.io pour le même tag avec dry_run: false ; le système de publication interroge d’abord chaque <crate>@<version> et ignore les versions déjà publiées. Consultez l’étape Publish pour connaître le dernier crate publié avec succès. Si la vérification préalable a échoué, aucune publication n’a été tentée et le problème est encore réversible.

La tâche scoop a échoué avec remote: Permission ... denied to <account> (403) : Il s’agit d’un problème d’autorisations, pas de manifeste : le jeton du bucket est désactivé ou ses autorisations sont insuffisantes. Faites tourner le jeton conformément à Rotation de SCOOP_BUCKET_TOKEN, puis déclenchez Scoop Bucket Canary pour confirmer la correction sans écrire dans le bucket. Relancez le publisher Scoop avec dry_run: false et vérifiez que la nouvelle version a bien été publiée dans le bucket. La récupération d’Excavator côté bucket reste en attente de zeroclaw-labs/scoop-zeroclaw#1, de l’autorisation d’écriture du workflow du dépôt et d’un test de bon fonctionnement par un mainteneur ; n’attendez pas qu’il répare une release avant que ces étapes soient terminées.

Le Scoop Bucket Canary hebdomadaire est passé au rouge : Le jeton a expiré ou a perdu ses droits d’écriture. Même procédure de rotation. Corrigez-le avant la prochaine version.

Homebrew Core n’est pas à jour : Homebrew n’est pas une tâche du workflow de publication. Consultez plutôt l’état de l’autobump de Homebrew et la procédure documentée pour effectuer le bump manuellement, au lieu d’ajouter un jeton de fork du dépôt.

La tâche AUR a échoué avec The AUR is down due to maintenance : Il s’agit d’une panne en amont, pas d’un problème d’identifiants. AUR_SSH_KEY est valide si le journal affiche une empreinte de clé sous SSH key diagnostics et si l’échec vient du serveur plutôt que de SSH. L’éditeur effectue cinq tentatives sur environ sept minutes, avec un délai d’expiration strict pour la tâche. Chaque tentative recrée le clone du paquet actuel et s’arrête au lieu de le rétrograder si une autre exécution a déjà publié une version plus récente. Le fait d’atteindre l’erreur de maintenance signifie que la fenêtre a dépassé le budget de tentatives. Attendez le retour de aur.archlinux.org, puis relancez Pub AUR Package sur la balise de version avec dry_run: true, puis dry_run: false. Confirmez le résultat avec curl -fsS 'https://aur.archlinux.org/rpc/v5/info?arg%5B%5D=zeroclawlabs', ou lancez simplement AUR Freshness Check. Ignorer cette étape laisse l’AUR prendre silencieusement du retard jusqu’à ce que la vérification hebdomadaire le détecte.

L’AUR est plus récent qu’une version stable volontairement rétrogradée : vérifiez le tag de rollback et le contenu du paquet. Si le paquet publié possède un epoch non nul que le tag de rollback ne contient pas, ne redéclenchez pas l’ancien tag : les métadonnées de la version proviennent du tag immuable, de sorte que les modifications de la branche par défaut ne peuvent pas changer cette exécution. Préparez plutôt une version stable avec un numéro supérieur contenant le code rétabli, ajoutez l’affectation epoch= correspondante à dist/aur/PKGBUILD, exécutez cargo generate installers pour régénérer dist/aur/.SRCINFO, vérifiez les deux fichiers, fusionnez, puis créez un nouveau tag de version. Le contrôle d’actualité reste en échec jusqu’à la publication de ce tag. N’utilisez jamais allow_downgrade pour franchir une limite d’epoch. Pour un rollback au sein du même epoch, exécutez une fois le workflow manuel Pub AUR Package avec dry_run: true afin de valider la génération des métadonnées et le côté cible du garde-fou de version, puis exécutez-le avec dry_run: false et allow_downgrade: true. Le garde-fou hors simulation compare en outre le clone AUR fraîchement récupéré. Cette surcharge n’existe que lors d’un déclenchement manuel ; l’interface réutilisable ne déclare pas cette entrée et ne peut donc pas la demander. Ne l’utilisez jamais pour contourner des métadonnées AUR malformées ou une incohérence de version inexpliquée.

La publication a été interrompue, car les fichiers du paquet diffèrent pour la même version : l’outil de publication refuse intentionnellement de remplacer des fichiers différents associés à un tuple epoch:pkgver-pkgrel existant. Examinez le diff. Un mainteneur AUR autorisé doit soit restaurer le PKGBUILD canonique et le .SRCINFO générés à partir de ce tag de version, soit fusionner une modification corrigée du code source et la publier sous un nouveau tag de version stable. Modifier la branche par défaut et redéclencher l’ancien tag ne peut pas fonctionner, car l’outil de publication lit les métadonnées depuis le tag immuable.

La publication signale une version actuelle sur AUR non numérique ou autrement mal formée : L’outil de publication automatisé refuse intentionnellement de poursuivre, et allow_downgrade ne peut pas contourner des métadonnées malformées. Un mainteneur AUR autorisé doit réparer le paquet en effectuant un envoi manuel vers AUR avec une version bien formée epoch:pkgver-pkgrel, la vérifier via le RPC AUR, puis relancer l’outil de publication normal. N’affaiblissez pas le contrôle pour rendre l’état publié malformé comparable.

Suppression des workflows hérités

Plusieurs workflows de publication automatique qui se trouvaient auparavant dans .github/workflows/ ont été supprimés car ils contournaient la revue ou publiaient de manière irréversible. Ils ne sont plus présents ; si l’un d’eux réapparaît dans une PR, traitez-le comme une régression et bloquez-la :

L’inventaire complet des workflows restants (automatiques et manuels) se trouve dans CI & Actions.

Vers quoi cela évolue

Ce runbook et release-stable-manual.yml sont une transition, pas une finalité.

L’état final cible :

• release-plz gère automatiquement les incréments de version et les changelogs
• Un seul fichier release.yml remplace l’assemblage hétéroclite actuel de sous-workflows
• La provenance SLSA est intégrée au pipeline
• L’équipe publie les versions en fusionnant une PR de release, et non en suivant un runbook

En attendant que cela soit en place, utilisez ce processus. Chaque version que vous publiez manuellement à l’aide de ce runbook constitue un exercice qui éclaire ce que l’automatisation devra accomplir.