Publier une version : SemVer, tags et releases

Publier une version, c'est figer un état du code sous un numéro (un tag Git comme v2.5.0), produire les artefacts correspondants (image Docker, archive, exécutable) et documenter ce qui a changé (une release et un CHANGELOG). Dans un pipeline, le tag déclenche tout le reste automatiquement. Ce chapitre explique le versionnage sémantique, les messages de commit normalisés, le workflow de publication sur un tag, l'automatisation du numéro et du CHANGELOG, et la protection des versions publiées.

Le versionnage sémantique (SemVer)

Le versionnage sémantique (Semantic Versioning, SemVer) donne un sens à chaque chiffre d'un numéro MAJEUR.MINEUR.CORRECTIF (tags et versions dans Git) :

Quelques règles complètent le système :

• une pré-version s'écrit avec un tiret : 2.5.0-rc.1 (release candidate), 3.0.0-beta.2 ; elle précède la version finale (2.5.0-rc.1 < 2.5.0) ;
• en version 0.x, tout peut changer : l'API n'est pas encore considérée comme stable ; par convention (npm, Cargo), un changement incompatible incrémente alors le chiffre MINEUR et une fonctionnalité ou une correction le CORRECTIF, mais beaucoup de projets incrémentent aussi le MINEUR pour une fonctionnalité ;
• un numéro publié ne se réutilise jamais : si la 2.5.0 contient un bug, on publie la 2.5.1, on ne remplace pas la 2.5.0.

Pour une API comme sorbier-frais, « incompatible » se juge du point de vue de ceux qui l'appellent : l'application mobile et l'interface Web. Ajouter un champ à une réponse JSON est compatible ; renommer un champ ne l'est pas.

Des messages de commit normalisés

La convention Conventional Commits structure les messages de commit avec un type (Conventional Commits) :

feat: ajoute l'export CSV des notes de frais
fix: arrondit les indemnités au centime
docs: complète le README avec la procédure de déploiement
feat!: renomme le champ montant en montant_ttc dans l'API

Le type indique directement l'incrément de version :

C'est ce qui permet à un outil de calculer seul le prochain numéro et de rédiger le CHANGELOG.

Tenir un CHANGELOG

Le fichier CHANGELOG.md résume, version par version, ce qui change pour ceux qui utilisent le logiciel. Le format le plus répandu, Keep a Changelog, range les changements par catégorie (Ajouté, Modifié, Corrigé, Supprimé, Sécurité), la version la plus récente en haut, avec sa date.

C'est aussi ce que demande l'indicateur de la compétence « Intégrer en continu les versions d'une solution applicative » de l'E6 SLAM : « une documentation des versions accompagne l'intégration ». Un CHANGELOG tenu à jour, des tags et des releases en sont la preuve directe (les compétences de l'E6 SLAM).

Le workflow de publication sur un tag

Pour publier la version 2.5.0, Lina met à jour le numéro, crée le tag et pousse :

npm version minor          # 2.4.1 → 2.5.0 dans package.json et package-lock.json, commit « 2.5.0 » et tag v2.5.0
git push --follow-tags     # pousse le commit et le tag

Le tag v2.5.0 déclenche ce workflow :

name: Publication

on:
  push:
    tags: ['v*.*.*']

permissions:
  contents: read

jobs:
  verifier:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - name: Vérifier que le tag correspond à package.json
        run: test "v$(node -p "require('./package.json').version")" = "$GITHUB_REF_NAME"
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          package-manager-cache: false
      - run: npm ci
      - run: npm test -- --ci

  release:
    needs: verifier
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v7
      - name: Construire l'archive
        run: git archive --format=zip --prefix="sorbier-frais-$GITHUB_REF_NAME/" -o "sorbier-frais-$GITHUB_REF_NAME.zip" HEAD
      - name: Créer la release
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          gh release create "$GITHUB_REF_NAME" \
            --title "sorbier-frais $GITHUB_REF_NAME" \
            --generate-notes \
            --verify-tag \
            "sorbier-frais-$GITHUB_REF_NAME.zip"

En parallèle, le workflow Docker du chapitre 9, déclenché lui aussi par les tags v*, publie les images 2.5.0 et 2.5. La production peut alors déployer 2.5.0, une étiquette qui parle à tout le monde.

Automatiser le numéro et le CHANGELOG

Choisir le numéro et écrire le CHANGELOG à la main est source d'oublis. Deux outils s'appuient sur Conventional Commits pour le faire :

• release-please (de Google) tient en permanence une pull request de publication, mise à jour à chaque fusion sur main : elle contient le nouveau numéro et les nouvelles entrées du CHANGELOG. Quand l'équipe décide de publier, elle fusionne cette pull request ; l'outil crée alors le tag et la release.
• semantic-release publie automatiquement à chaque fusion sur main qui contient un feat ou un fix, sans pull request intermédiaire.

name: Release Please

on:
  push:
    branches: [main]

permissions:
  contents: write
  pull-requests: write

jobs:
  release-please:
    runs-on: ubuntu-latest
    outputs:
      publiee: ${{ steps.release.outputs.release_created }}
      tag: ${{ steps.release.outputs.tag_name }}
    steps:
      # Action d'un éditeur tiers : dans un vrai projet, épingle-la sur une empreinte de commit
      - id: release
        uses: googleapis/release-please-action@v5
        with:
          release-type: node

  image:
    needs: release-please
    if: needs.release-please.outputs.publiee == 'true'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Construction de l'image pour ${{ needs.release-please.outputs.tag }}"

Protéger les versions publiées

Une version publiée doit rester ce qu'elle était. Sur GitHub :

• un ruleset de tags (Settings, Rules, Rulesets, New tag ruleset) sur le motif v* réserve la création des tags de version aux mainteneurs et interdit leur suppression et leur déplacement ;
• les releases immuables, une option du dépôt, empêchent de modifier le tag et les fichiers d'une release une fois publiée ;
• un tag signé (git tag -s v2.5.0) prouve qui a créé la version (signer ses tags) ;
• une attestation de provenance des fichiers publiés, produite dans le workflow par l'action officielle actions/attest-build-provenance (avec les permissions id-token: write et attestations: write), permet à quiconque de vérifier avec gh attestation verify qu'un fichier a bien été construit par ce workflow, à partir de ce commit.

C'est exactement ce que la règle de l'action épinglée demande aux autres : des versions qui ne bougent pas.

Avec GitLab

publier-release:
  stage: deploy
  image: registry.gitlab.com/gitlab-org/cli:latest
  rules:
    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
  script:
    - echo "Publication de la version $CI_COMMIT_TAG"
  release:
    tag_name: $CI_COMMIT_TAG
    name: "sorbier-frais $CI_COMMIT_TAG"
    description: "Voir CHANGELOG.md pour le détail des changements."

Le mot-clé release crée la release GitLab à partir du tag ; l'image cli contient l'outil glab qui s'en charge. Les tags protégés (Settings, Repository, Protected tags) réservent la création des tags v* aux mainteneurs, et les variables protégées ne sont transmises qu'à leurs pipelines.

Exercices

fix: arrondit les indemnités au centime
docs: complète le README
feat: ajoute l'export CSV des notes de frais
chore: met à jour Jest
ci: ajoute l'analyse CodeQL

Run test "v$(node -p "require('./package.json').version")" = "$GITHUB_REF_NAME"
Error: Process completed with exit code 1.

name: Publication

on:
  push:
    tags: ['v*.*.*']

permissions:
  contents: read

jobs:
  release:
    runs-on: windows-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-dotnet@v6
        with:
          dotnet-version: '10.0.x'
      - run: dotnet publish GestStock/GestStock.csproj --configuration Release --output publication
      - name: Compresser
        shell: pwsh
        run: Compress-Archive -Path publication/* -DestinationPath "GestStock-$env:GITHUB_REF_NAME.zip"
      - name: Créer la release
        shell: pwsh
        env:
          GH_TOKEN: ${{ github.token }}
        run: gh release create $env:GITHUB_REF_NAME "GestStock-$env:GITHUB_REF_NAME.zip" --generate-notes --verify-tag