Skip to main content

Releases

Introduction au versionnement sémantique​

Le versionnement sémantique (ou SemVer) est une convention de numérotation des versions qui permet de communiquer facilement la nature et l'impact des changements apportés à un projet. Selon cette convention, chaque version est composée de trois nombres : MAJOR.MINOR.PATCH.

  • MAJOR : Version incrémentée pour des changements incompatibles avec les versions précédentes.
  • MINOR : Version incrémentée pour l'ajout de fonctionnalités compatibles avec les versions précédentes.
  • PATCH : Version incrémentée pour des corrections de bugs compatibles avec les versions précédentes.

Par exemple, la version 2.3.1 indique la deuxième version majeure, la troisième version mineure, et la première correction de bug depuis la dernière version mineure.

Qu'est-ce que Semantic Release ?​

Semantic Release est un outil qui automatise entièrement le processus de versionnement et de publication de votre package. En analysant les messages de commit (suivant la convention Conventional Commits), il détermine automatiquement la prochaine version, génère des notes de version et publie la nouvelle version.

Avantages de Semantic Release​

  • Automatisation complète : Élimine la gestion manuelle des versions et des releases.
  • Cohérence : Assure que le versionnement respecte la spécification SemVer.
  • Documentation automatique : Génère automatiquement des changelogs détaillés.
  • Intégration CI/CD : S'intègre parfaitement dans les pipelines d'intégration continue.

Installation et configuration de Semantic Release​

Installation​

npm install semantic-release @semantic-release/git @semantic-release/github @semantic-release/changelog @semantic-release/npm --save-dev

Configuration​

Créez un fichier .releaserc.json à la racine de votre projet :

{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/npm",
    ["@semantic-release/git", {
      "assets": ["package.json", "CHANGELOG.md"],
      "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
    }],
    "@semantic-release/github"
  ]
}

Explication des plugins​

  • commit-analyzer : Analyse les commits pour déterminer la prochaine version.
  • release-notes-generator : Génère les notes de version basées sur les commits.
  • changelog : Met à jour le fichier CHANGELOG.md avec les nouvelles notes de version.
  • npm : Met à jour la version dans package.json et publie le package sur npm si configuré.
  • git : Commit les fichiers mis à jour (package.json, CHANGELOG.md) et crée un tag Git.
  • github : Crée une release GitHub avec les notes de version.

Configuration pour les projets privés​

Si votre projet n'est pas destiné à être publié sur npm, vous pouvez configurer Semantic Release pour qu'il ne tente pas de publier sur npm :

{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    ["@semantic-release/npm", {
      "npmPublish": false
    }],
    ["@semantic-release/git", {
      "assets": ["package.json", "CHANGELOG.md"],
      "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
    }],
    "@semantic-release/github"
  ]
}

Intégration avec GitHub Actions​

Pour automatiser le processus de release avec GitHub Actions, ajoutez un workflow spécifique dans .github/workflows/release.yml :

name: Release

on:
  push:
    branches: [main]

jobs:
  release:
    name: Release
    runs-on: ubuntu-latest
    if: "!contains(github.event.head_commit.message, 'skip ci')"
    
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
          persist-credentials: false
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run tests
        run: npm test
      
      - name: Build
        run: npm run build --if-present
      
      - name: Semantic Release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npx semantic-release

Explication du workflow​

  1. Le workflow s'exécute uniquement sur les pushes vers la branche main.
  2. Il vérifie d'abord si le message de commit ne contient pas "skip ci" pour éviter les boucles.
  3. Il checkout le code avec toute l'historique Git (nécessaire pour Semantic Release).
  4. Il installe les dépendances, exécute les tests et construit l'application.
  5. Enfin, il exécute Semantic Release avec les tokens GitHub et npm nécessaires.

Configuration des tokens GitHub et npm​

Pour que Semantic Release fonctionne correctement, vous devez configurer les tokens d'accès :

Token GitHub​

Le GITHUB_TOKEN est automatiquement fourni par GitHub Actions et n'a pas besoin d'être configuré manuellement.

Token npm (si publication sur npm)​

Si vous publiez votre package sur npm, vous devez créer un token npm et l'ajouter comme secret GitHub :

  1. Connectez-vous à votre compte npm sur npmjs.com.
  2. Allez dans "Access Tokens" et créez un nouveau token avec les permissions "Read and publish".
  3. Dans votre dépôt GitHub, allez dans Settings > Secrets and variables > Actions.
  4. Créez un nouveau secret nommé NPM_TOKEN avec la valeur du token npm.

Fonctionnement de Semantic Release​

Voici comment Semantic Release détermine la prochaine version :

  1. Analyse des commits : Semantic Release analyse tous les commits depuis la dernière version.
  2. Détermination de la version : En fonction des types de commits :
    • fix: → Incrémente la version de patch (1.0.0 → 1.0.1)
    • feat: → Incrémente la version mineure (1.0.0 → 1.1.0)
    • BREAKING CHANGE: dans le corps ou le footer, ou feat!: → Incrémente la version majeure (1.0.0 → 2.0.0)
  3. Génération des notes : Crée des notes de version détaillées basées sur les commits.
  4. Publication : Met à jour les fichiers, crée un tag Git, et publie la release sur GitHub et npm si configuré.

Personnalisation avancée​

Règles de versionnement personnalisées​

Vous pouvez personnaliser les règles de versionnement dans votre fichier .releaserc.json :

{
  "plugins": [
    ["@semantic-release/commit-analyzer", {
      "preset": "angular",
      "releaseRules": [
        {"type": "docs", "scope": "README", "release": "patch"},
        {"type": "refactor", "release": "patch"},
        {"type": "style", "release": "patch"}
      ]
    }],
    // autres plugins...
  ]
}

Génération de changelogs personnalisés​

Vous pouvez personnaliser le format des changelogs générés :

{
  "plugins": [
    // autres plugins...
    ["@semantic-release/release-notes-generator", {
      "preset": "angular",
      "writerOpts": {
        "commitsSort": ["subject", "scope"]
      }
    }],
    // autres plugins...
  ]
}

Bonnes pratiques​

Pour tirer le meilleur parti de Semantic Release :

  1. Suivez strictement la convention Conventional Commits pour tous vos messages de commit.
  2. Utilisez des hooks pre-commit (comme nous l'avons vu avec Husky) pour vérifier les messages de commit.
  3. Intégrez Semantic Release tôt dans votre projet pour bénéficier d'un historique de versions propre.
  4. Documentez le processus pour que tous les membres de l'équipe comprennent comment les versions sont générées.
  5. Testez le process en local avec npx semantic-release --dry-run avant de l'implémenter en CI.

En suivant ces pratiques, vous automatiserez entièrement le processus de versionnement de votre application, ce qui vous permettra de vous concentrer sur le développement tout en maintenant une documentation et un versionnement cohérents.