Appearance

Brancher un projet sur @spektrum/release-util ​

Ce guide accompagne un mainteneur dans la mise en place d'un dépôt tout neuf (ou jusqu'ici artisanal) sur le workflow de release Spektrum. État final : chaque release est une MR à un seul commit de sujet chore(release): X.Y.Z[-staging.N], que la CI reprend au merge pour taguer et publier.

Pour le pourquoi du workflow, lire RELEASING.md. Pour le câblage de .gitlab-ci.yml, la skill .claude/skills/spektrum-release-pipeline/SKILL.md détient le YAML canonique. Pour la surface des commandes, voir commandes.md.

Prérequis ​

  • Node ≥ 20 et git sur le PATH.
  • Un dépôt GitLab sur gitlab.spektrum-suisse.ch (ou là où vit le groupe Spektrum).
  • Accès push à ce dépôt via clé SSH ou identifiants HTTPS. Le flux release local s'appuie sur l'auth git existante — aucun token d'API GitLab en local.
  • Pour les projets qui publient sur npm : un token du registre interne. La CI a le sien.

1. Pointer npm vers le registre interne ​

Le scope @spektrum/* vit sur le registre npm interne. À configurer une fois par machine :

bash
npm config set @spektrum:registry https://npm.internal.spektrum-suisse.ch

C'est scopé — les autres paquets tapent toujours le registre public. Il faut aussi être authentifié contre le registre interne (npm login --registry=https://npm.internal.spektrum-suisse.ch). Vérifier :

bash
npx --yes @spektrum/release-util@latest --version

Une chaîne de version doit s'afficher. Un 401 ou « package not found » signale une config de registre ou une auth incorrecte.

2. Confirmer que le dépôt est en modèle trunk ​

release-util ne fonctionne que sur un dépôt trunk-based : une seule branche longue durée (main ou master) dans laquelle tout fusionne. Avant de brancher :

  • Exactement une branche longue durée. S'il y a un develop à côté de main, en choisir une et retirer l'autre.
  • Le « Default branch » du projet GitLab correspond à cette branche.
  • L'équipe s'engage aux commits conventionnels désormais. Le calcul de version lit les messages de commit ; sans respect de la spec, les bumps seront faux.

Si vous migrez depuis gitflow ou un autre flux, cette conversation doit avoir lieu avant de brancher le pipeline. La CLI ne fera pas le pont sur un historique non-trunk ; elle refusera de releaser tant que les préconditions ne tiennent pas.

3. Générer .release-it.json ​

Depuis un checkout propre du trunk :

bash
npx --yes @spektrum/release-util@latest init

Cela écrit .release-it.json à la racine avec des défauts sensés et un trunkBranch auto-détecté. Ouvrir le fichier généré et confirmer que trunkBranch correspond à la branche par défaut GitLab. Voir configuration.md pour le détail des clés. Committer le fichier :

bash
git add .release-it.json
git commit -m "chore: add release-util config"

4. Ajouter l'application des commits conventionnels ​

Le calcul de version lit les commits conventionnels. Les imposer à trois endroits pour qu'un mauvais commit n'atteigne jamais le trunk :

  1. Hook commit-msg local. Ajouter @commitlint/cli + @commitlint/config-conventional en devDependencies et câbler via pre-commit (ou husky, ou le framework de hooks du projet).
  2. Job de lint CI. Ajouter un job commit-lint qui lance commitlint sur la plage de commits de la MR.
  3. Push rule GitLab. Settings → Repository → Push rules → imposer un motif de sujet de commit conventionnel. Défense en profondeur si les hooks/CI sont contournés.

Chaque couche est contournable seule ; la combinaison est robuste.

5. Câbler .gitlab-ci.yml ​

La forme canonique du pipeline (lint, test, publish, tag-pipeline) est documentée dans la skill .claude/skills/spektrum-release-pipeline/SKILL.md — l'utiliser comme source de vérité. Les invariants et les deux saveurs (npm / Docker) sont décrits dans integration-ci.md.

6. Configurer les réglages projet GitLab requis ​

Méthode de merge (pas de squash sur release/*), push rules, variables RELEASE_TOKEN / NPM_TOKEN, badges : tout est détaillé dans integration-ci.md. Ces réglages vivent dans l'UI et le workflow déraille silencieusement si l'un d'eux est faux.

7. Première release de bout en bout ​

Couper une release pour valider le câblage. Choisir un projet ayant au moins un commit publiable depuis le dernier tag (ou, sur un dépôt neuf, depuis le commit initial).

bash
git checkout main && git pull --ff-only
npx --yes @spektrum/release-util@latest doctor
# Vert ? Bien. Sinon, corriger et relancer.

npx --yes @spektrum/release-util@latest release --env staging --dry-run
# Se lit comme attendu ? Couper pour de vrai.

npx --yes @spektrum/release-util@latest release --env staging
# → ouvre une MR, affiche l'URL.

Relire la MR, merger en merge-commit ou fast-forward (PAS squash), et observer le pipeline :

  1. Le job publish se déclenche sur le trunk.
  2. eval $(release-util tag) crée et pousse X.Y.Z-staging.1.
  3. L'étape d'artefact publie sur npm (--tag staging) ou pousse l'image Docker (X.Y.Z-staging.1 + staging-latest).
  4. release-util badges --out badges/ écrit les deux SVG en artefacts (ou release-util badge --env <prod|staging> pour n'en produire qu'un, personnalisable).

Une fois le staging validé, promouvoir en prod :

bash
npx --yes @spektrum/release-util@latest release --env prod

Même flux, retire le suffixe -staging.N, publie avec --tag latest (ou tag d'image :latest).

8. Checklist de vérification ​

  • [ ] .release-it.json à la racine, trunkBranch correspond au défaut GitLab.
  • [ ] .gitlab-ci.yml parse (CI Lint GitLab ou glab ci lint).
  • [ ] Hook commit-msg local installé ; job commitlint en CI ; push rule sur le trunk.
  • [ ] RELEASE_TOKEN défini (Protégé + Masqué, scope write_repository).
  • [ ] NPM_TOKEN défini si publication npm.
  • [ ] Squash-on-merge désactivé pour les MR release/*.
  • [ ] Une vraie release staging de bout en bout : branche coupée, MR ouverte, mergée, tag poussé, artefact publié, badges produits.
  • [ ] Une vraie release prod de bout en bout.

Et ensuite ​

  • Usage quotidien : commandes.md pour la surface complète des commandes.
  • Politique opérationnelle : RELEASING.md pour les hypothèses trunk-based, l'invariant à un seul commit, le protocole de correction en vol et la politique de hotfix.
  • Modifier le pipeline : la skill spektrum-release-pipeline détient le YAML canonique et les modes d'échec courants.

Si quelque chose déraille silencieusement après l'onboarding, les trois premiers endroits à vérifier sont : (1) la méthode de merge (le squash revient en douce), (2) le scope de RELEASE_TOKEN, (3) le rules: du job publish. Voir depannage.md.

Contributors

No contributors

Changelog

No recent changes