Documentation @spektrum/release-util
Documentation vivante du projet, en français. Ces pages décrivent l'état actuel de l'outil — elles évoluent avec le code et ne sont pas un journal de décisions.
Pour le pourquoi du workflow (modèle trunk-based, invariant à un seul commit, correction en avant, politique de hotfix), voir
RELEASING.md. Pour le pitch « installation + à quoi ça sert », voir leREADME.mdracine.
Vue d'ensemble
@spektrum/release-util est un binaire unique (release-util) qui coupe des releases « façon Spektrum ». Le flux local (validation → version → branche → changelog via release-it → push → ouverture de MR GitLab) ne nécessite aucun token d'API GitLab : il s'appuie sur l'authentification git existante et ouvre les MR via les push options GitLab. Le tag, la publication et les badges sont délibérément laissés à la CI — c'est ce qui garde le flux local sans authentification et la CI reproductible.
Le binaire se découpe en huit sous-commandes : cinq pensées pour le poste du développeur, trois pour le pipeline GitLab. Rien dans l'ensemble local ne requiert de token GitLab ; tout l'ensemble CI est agnostique vis-à-vis de l'authentification — le YAML configure git remote set-url --push avant d'appeler le binaire.
local : CI :
release-util init release-util tag
release-util doctor release-util detect
release-util next-version release-util badge
release-util release
release-util hotfix
release-util cleanupLa commande phare est release. Le reste existe pour que chaque étape du flux soit scriptable indépendamment.
Carte de la documentation
| Page | Contenu |
|---|---|
architecture/commandes.md | Surface complète des sous-commandes : flags, entrées, sorties, codes de sortie. |
architecture/environnements-et-versioning.md | Les trois environnements (staging, prod, feature), le calcul de version, le compteur staging, les previews. |
architecture/configuration.md | .release-it.json, la clé trunkBranch, l'intégration release-it et la frontière du changelog. |
architecture/integration-ci.md | Forme canonique du pipeline, réglages projet GitLab requis, recettes d'intégration. |
architecture/onboarding.md | Pas-à-pas pour brancher un nouveau dépôt sur le workflow. |
architecture/depannage.md | FAQ et dépannage des symptômes courants. |
architecture/mcp.md | Serveur MCP @spektrum/release-util-mcp : outils, API, configuration consommateur. |
Surface d'invocation
L'outil est publié sur le registre npm interne ; l'invocation canonique passe par npx :
npx --yes @spektrum/release-util@latest <commande> [flags]@latest est intentionnel. Sans lui, npx met en cache la première version résolue sur une machine donnée — un correctif du script de release n'atteindrait jamais la moitié de l'équipe. Ne pas épingler une version précise en CI sans raison concrète.
Prérequis : Node ≥ 20 et git sur le PATH. Fonctionne sur macOS, Linux et Windows (PowerShell, cmd, Git Bash, WSL).
Flags de premier niveau
Applicables à n'importe quelle sous-commande :
| Flag | Description |
|---|---|
--verbose | Journalise chaque invocation git. Peut apparaître n'importe où avant la sous-commande ; les sous-commandes l'acceptent aussi localement. |
--help, -h | Aide de premier niveau, ou release-util <cmd> --help pour l'aide par commande. |
--version, -V | Affiche la version de la CLI elle-même. |
--help et --version sont positionnels : avant toute sous-commande ils court-circuitent vers le gestionnaire de premier niveau ; après une sous-commande ils sont transmis au parseur de la sous-commande.
Codes de sortie
| Code | Signification |
|---|---|
0 | Succès (y compris le chemin de succès de --dry-run). |
1 | Échec à l'exécution (précondition, git, réseau, etc.). Le message d'erreur et l'indice vont sur stderr. |
2 | Erreur d'usage (mauvais flag, --env manquant, sous-commande inconnue). |
3 | Échec de précondition de doctor (sentinelle — distincte de 1 pour pouvoir brancher dessus en CI). |
3 est un contrat figé : il ne provient que de doctor lorsqu'une précondition échoue. La classification usage/exécution vit dans looksLikeUsageError() (src/cli.ts).