Versionner proprement avec Changesets et Claude Code

Claude Code peut accélérer les releases, mais le versioning ne doit pas être laissé à une décision vague. Un breaking change publié en patch casse les builds des utilisateurs. Un package interne publié par erreur sur npm laisse une trace difficile à nettoyer. Changesets apporte une discipline simple: chaque PR doit dire quel package change, quel bump est nécessaire et pourquoi.

Ce guide présente un flux concret avec Claude Code et Changesets: bases de SemVer, release notes, packages en monorepo, packages privés ou internes, GitHub Actions, risques de npm publish, qualité du CHANGELOG et prompts de revue pour éviter les mauvais bumps générés par IA. Les références officielles sont SemVer, Changesets, la documentation npm publishing et GitHub Actions. Côté ClaudeCodeLab, lisez aussi bonnes pratiques CLAUDE.md, configuration CI/CD et gestion de monorepo.

Fixer SemVer avant d’automatiser

SemVer signifie versioning sémantique. Dans 1.4.2, le format est major.minor.patch. patch corrige un bug sans changer le contrat public. minor ajoute une fonctionnalité compatible. major signale que l’utilisateur devra peut-être modifier son code.

Le contrat public ne se limite pas aux fonctions exportées. Il comprend aussi props React, tokens CSS, flags CLI, codes de sortie, comportement par défaut et types TypeScript exportés. Claude Code doit recevoir cette règle explicitement, sinon il risque de juger le bump à partir de la taille du diff.

Exemples utiles:

Cas	Risque	Revue par Claude Code
UI package	props, variants, tokens CSS, peer dependencies	cohérence entre bump et API publique
CLI package	flags, commandes, exit codes	cohérence README, tests, code
Monorepo	ranges de dépendances internes	package dépendant à publier aussi
Package interne	publication accidentelle	private, ignore, registry, token

Configuration initiale

Installez et initialisez Changesets.

npm install -D @changesets/cli @changesets/changelog-github
npx changeset init

Configuration de départ:

{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": [
    "@changesets/changelog-github",
    {
      "repo": "your-org/your-repo"
    }
  ],
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": []
}

fixed garde un groupe de packages sur la même version. linked bump des packages liés ensemble, tout en gardant leurs numéros propres. updateInternalDependencies contrôle la mise à jour des ranges internes. En monorepo, un projet peut compiler localement avec workspace:* mais échouer après publication si les ranges ne sont pas cohérents.

Ajoutez des scripts explicites:

{
  "scripts": {
    "changeset": "changeset",
    "changeset:status": "changeset status --since=origin/main",
    "version": "changeset version",
    "release": "changeset publish",
    "build": "tsc -p tsconfig.json",
    "test": "vitest run"
  }
}

Écrire le changeset

Pour chaque PR qui change un package public:

npx changeset

Exemple:

---
"@myapp/ui": minor
"@myapp/utils": patch
---

Add the `outline` variant to Button and keep the existing `solid` and `ghost` variants compatible.

Fix `formatCurrency` so it handles zero-decimal currencies without rounding errors.

@myapp/ui est en minor car une option compatible est ajoutée. @myapp/utils est en patch car une fonction existante est corrigée. Suppression de prop, renommage de flag CLI ou changement de comportement par défaut doivent être traités comme candidats major.

Prompt recommandé:

Lis le diff de la PR actuelle et prépare un changeset Changesets.

Règles:
- Respecte SemVer: breaking change = major, fonctionnalité compatible = minor, correction = patch
- Ne modifie pas directement la version dans package.json
- N'exécute pas npm publish
- N'inclus pas les packages private: true dans le plan de publication

Retourne:
- packages modifiés
- bump recommandé pour chaque package
- justification
- contenu proposé pour .changeset/*.md
- points incertains à valider humainement

Monorepos et packages internes

Un dépôt réel contient souvent des packages publiables et des apps qui ne doivent jamais être publiées. Exemple:

{
  "name": "@myapp/app",
  "private": true,
  "version": "0.0.0",
  "scripts": {
    "build": "next build"
  },
  "dependencies": {
    "@myapp/ui": "workspace:*"
  }
}

Exclusion côté Changesets:

{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": [
    "@changesets/changelog-github",
    {
      "repo": "your-org/your-repo"
    }
  ],
  "commit": false,
  "fixed": [
    ["@myapp/core", "@myapp/cli"]
  ],
  "linked": [
    ["@myapp/ui", "@myapp/theme"]
  ],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": ["@myapp/app", "@myapp/docs"]
}

Pour un registry interne:

{
  "name": "@my-company/internal-kit",
  "version": "1.8.0",
  "publishConfig": {
    "registry": "https://npm.pkg.github.com",
    "access": "restricted"
  }
}

Séparez le token de ce registry du token npm public.

Release avec GitHub Actions

changesets/action crée la PR de version et publie après merge.

name: Release

on:
  push:
    branches:
      - main

concurrency: release-${{ github.ref }}

permissions:
  contents: write
  pull-requests: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: "https://registry.npmjs.org"

      - run: npm ci
      - run: npm test
      - run: npm run build

      - name: Create release PR or publish to npm
        uses: changesets/action@v1
        with:
          version: npm run version
          publish: npm run release
          title: "chore: version packages"
          commit: "chore: version packages"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Ajoutez un contrôle sur les PR:

name: Changeset Check

on:
  pull_request:
    branches:
      - main

permissions:
  contents: read

jobs:
  changeset:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx changeset status --since=origin/main

Une PR de documentation peut être exemptée, mais la règle doit être décidée par l’équipe. Ne laissez pas Claude Code ajouter une exception trop large pour faire passer la CI.

Qualité du CHANGELOG

Entrée faible:

---
"@myapp/ui": minor
---

Update Button.

Entrée utile:

---
"@myapp/ui": minor
---

Add `variant="outline"` to `Button`.

Existing `solid` and `ghost` variants keep the same props and class names. Teams using a custom theme should add `--button-outline-border` only if they want to override the default border color.

Prompt de revue:

Relis ce changeset comme texte public de CHANGELOG.

Vérifie:
- l'impact est compréhensible
- le texte correspond au bump major/minor/patch
- les étapes de migration existent si nécessaire
- les mots vagues comme "updated" ou "improved" ne remplacent pas les détails
- les noms de packages, fonctions et props existent

Liste les points suspects sous forme de questions. Ne réécris pas en silence.

Échecs fréquents

Premier échec: demander simplement “augmente la version”. Claude Code peut modifier package.json sans laisser de changeset.

Deuxième échec: publier un breaking change en minor. Même un changement de type TypeScript peut casser le build d’un consommateur.

Troisième échec: publier un package interne. Vérifiez private: true, ignore, publishConfig.registry, les permissions du token et npm pack --dry-run.

Quatrième échec: oublier un bump de dépendance interne. Si @myapp/core change, @myapp/cli peut aussi devoir sortir.

Vérification locale

Avant release:

npm run changeset:status
npm test
npm run build
npm run version -- --snapshot canary
git diff -- package.json package-lock.json pnpm-lock.yaml yarn.lock CHANGELOG.md
npm pack --dry-run

Le snapshot vérifie calcul de version et CHANGELOG sans publication. npm pack --dry-run montre le contenu du tarball, utile pour repérer .env, fixtures trop lourdes, docs internes ou build manquant.

Monétisation et adoption

Un release flow fiable soutient le revenu: UI kit, CLI, SDK ou template package peuvent devenir produits payants, formation d’équipe ou mission de conseil. Un mauvais bump abîme vite la confiance.

Pour l’appliquer à un vrai dépôt, la formation et consultation Claude Code peut aider à cadrer Changesets, CLAUDE.md, GitHub Actions, tokens npm, prompts de revue et règles de monorepo.

Résultat testé

J’ai vérifié ce flux sur un petit workspace npm: initialisation, changeset, changeset status, PR de release et garde-fous de publication. Claude Code rédige vite des release notes depuis un diff, mais son jugement SemVer seul reste fragile. Lui demander pourquoi un changement n’est pas breaking révèle plus vite les bumps minor ou patch discutables.