Changesets Frontend : Un guide complet de la gestion des versions

Dans le monde en constante évolution du développement frontend, la gestion efficace des changements et des versions est cruciale pour maintenir la stabilité du projet et assurer une collaboration fluide. Les "changesets" frontend offrent une solution puissante et flexible pour le contrôle de version, la gestion des dépendances et l'automatisation du processus de publication. Ce guide explore les subtilités des "changesets" frontend, couvrant tout, de la configuration de base à la configuration avancée, en offrant des exemples pratiques et des idées actionnables pour vous aider à maîtriser cet outil essentiel.

Que sont les "Changesets" Frontend ?

Frontend Changesets est un outil conçu pour gérer la versioning et la publication de packages JavaScript, en particulier au sein des monorepos. Il automatise le processus de création de journaux de modifications (changelogs), de mise à jour des versions de packages et de publication sur des registres de packages comme npm. Les "changesets" sont essentiellement de petits fichiers ciblés qui décrivent les modifications apportées à un package ou un composant spécifique. Ces fichiers sont ensuite utilisés pour générer les notes de version, mettre à jour les versions des packages et gérer les dépendances.

Comparé aux approches de versioning traditionnelles, Changesets offre plusieurs avantages clés :

• Collaboration améliorée : Les "changesets" rationalisent le processus de collaboration sur de grands projets impliquant plusieurs contributeurs. En définissant clairement l'impact de chaque changement, les "changesets" permettent aux membres de l'équipe de comprendre et de réviser plus facilement les contributions.
• Versions automatisées : Les "changesets" automatisent le processus de publication, réduisant le risque d'erreurs humaines et garantissant un versioning cohérent sur tous les packages.
• Transparence accrue : Les "changesets" fournissent un enregistrement transparent de tous les changements apportés au projet, ce qui facilite le traçage des bogues et la compréhension de l'évolution du code.
• Support des Monorepos : Les "changesets" sont particulièrement bien adaptés à la gestion des monorepos, où plusieurs packages sont hébergés dans un seul dépôt. Ils fournissent une approche centralisée et cohérente pour le versioning et la publication des packages au sein du monorepo.

Premiers pas avec les "Changesets" Frontend

Pour commencer à utiliser Frontend Changesets, vous devrez installer les packages nécessaires et initialiser l'outil dans votre projet. Voici un guide étape par étape :

1. Installation

Installez le package principal `@changesets/cli` en tant que dépendance de développement :

            npm install @changesets/cli --save-dev
# ou
yarn add @changesets/cli --dev
            

              
                Copy
              
            
          

2. Initialisation

Initialisez Changesets dans votre projet en exécutant la commande suivante :

            npx changeset init
            

              
                Copy
              
            
          

Cette commande créera un répertoire `.changeset` à la racine de votre projet, ainsi qu'un fichier de configuration (`.changeset/config.json`).

3. Configuration des "Changesets"

Le fichier `config.json` vous permet de personnaliser le comportement de Changesets. Voici une configuration typique :

            {
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "ignore": []
}
            

              
                Copy
              
            
          

Examinons chaque option :

• `changelog` : Spécifie l'adaptateur utilisé pour générer les entrées du journal des modifications. L'adaptateur par défaut `@changesets/cli/changelog` utilise le format Markdown.
• `commit` : Détermine si Changesets doit commiter automatiquement les modifications dans le dépôt. Définir cette option sur `false` vous permet de réviser et de commiter manuellement les changements.
• `fixed` : Un tableau de noms de packages qui doivent toujours être publiés ensemble avec la même version. Ceci est utile pour les packages qui sont étroitement couplés.
• `linked` : Un tableau de dépendances qui doivent être liées ensemble pendant le développement. Cela vous permet de tester les changements sur plusieurs packages sans les publier.
• `access` : Détermine le niveau d'accès des packages publiés. Le niveau d'accès par défaut `public` rend les packages publiquement disponibles sur npm.
• `baseBranch` : Spécifie la branche de base à comparer lors de la détermination des packages qui ont changé. Ceci est généralement défini sur la branche principale de votre dépôt (par exemple, `main`, `master`).
• `ignore` : Un tableau de fichiers ou de répertoires à ignorer lors de la détermination des packages qui ont changé.

Création d'un "Changeset"

Pour créer un "changeset", exécutez la commande suivante :

            npx changeset
            

              
                Copy
              
            
          

Cette commande vous invitera à sélectionner les packages qui ont été modifiés et à fournir une description des changements. La description doit être claire, concise et informative, expliquant le but et l'impact des changements. Par exemple :

            Fix: Correction d'un bug dans le composant bouton qui le faisait s'afficher incorrectement sur mobile.

Ce changeset corrige un bug dans le composant `Button` qui provoquait un rendu avec un style incorrect sur les appareils mobiles. Le problème était causé par un conflit de spécificité CSS. Ce changement résout le conflit et garantit que le composant bouton s'affiche correctement sur tous les appareils.
            

              
                Copy
              
            
          

Changesets générera ensuite un fichier Markdown dans le répertoire `.changeset` contenant les informations que vous avez fournies. Ce fichier sera utilisé ultérieurement pour générer les notes de version et mettre à jour les versions des packages.

Gestion des dépendances avec les "Changesets"

Changesets peut également être utilisé pour gérer les dépendances entre les packages au sein d'un monorepo. Lors de la création d'un "changeset", vous pouvez spécifier quels packages dépendent du package modifié. Cela garantit que les packages dépendants sont également mis à jour lorsque le package modifié est publié.

Par exemple, si vous avez deux packages, `package-a` et `package-b`, et que `package-b` dépend de `package-a`, vous pouvez créer un "changeset" pour `package-a` et spécifier que `package-b` en dépend. Lorsque vous exécutez la commande `version` (décrite ci-dessous), Changesets mettra automatiquement à jour la version de `package-b` pour refléter les changements dans `package-a`.

Versionnement et Publication

Une fois que vous avez créé un ou plusieurs "changesets", vous pouvez utiliser la commande `version` pour mettre à jour les versions des packages et générer les journaux de modifications.

            npx changeset version
            

              
                Copy
              
            
          

Cette commande va :

• Lire les "changesets" dans le répertoire `.changeset`.
• Déterminer la mise à jour de version appropriée pour chaque package en fonction des "changesets".
• Mettre à jour les fichiers `package.json` avec les nouvelles versions.
• Générer les entrées du journal des modifications pour chaque package.
• Commiter les changements dans le dépôt.

Après avoir exécuté la commande `version`, vous pouvez publier les packages sur npm en utilisant la commande `publish` :

            npx changeset publish
            

              
                Copy
              
            
          

Cette commande va :

• Compiler les packages (si nécessaire).
• Publier les packages sur npm.
• Supprimer les "changesets" du répertoire `.changeset`.

Intégration des "Changesets" avec CI/CD

Changesets est conçu pour être intégré aux pipelines CI/CD (intégration continue/livraison continue). Cela vous permet d'automatiser le processus de publication et de garantir que les changements sont déployés rapidement et de manière fiable.

Voici un flux de travail CI/CD typique pour Changesets :

1. Commit des changements : Les développeurs committent les changements dans le dépôt, y compris les "changesets".
2. Build CI : Le système CI exécute les tests et compile le projet.
3. Versionnement et Publication : Le système CI exécute les commandes `version` et `publish` de Changesets pour mettre à jour les versions des packages, générer les journaux de modifications et publier les packages sur npm. Cette étape utilise souvent un jeton ou des identifiants automatisés pour l'accès à npm.
4. Déploiement : Le système CI déploie les packages mis à jour dans l'environnement de production.

Plusieurs fournisseurs CI/CD offrent un support intégré pour Changesets. Par exemple, GitHub Actions propose une action dédiée à l'exécution de Changesets :

            name: Release

on:
  push:
    branches:
      - main

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v3
        with:
          node-version: 16
      - name: Installer les dépendances
        run: npm install
      - name: Créer une Pull Request de Release ou publier sur npm
        id: changesets
        uses: changesets/action@v1
        with:
          # Ceci garantit que nous pouvons lire le jeton même s'il n'est pas
          # disponible sur la PR. Cela évite une erreur dans
          # l'étape de publication ci-dessous.
          publish: npm run release
          version: npm run version
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

            

              
                Copy
              
            
          

Ce flux de travail exécute automatiquement les commandes `version` et `publish` chaque fois que des changements sont poussés sur la branche `main`. Il crée également une pull request contenant les fichiers `package.json` mis à jour et les journaux de modifications.

Configuration Avancée

Changesets offre plusieurs options de configuration avancées qui vous permettent de personnaliser l'outil pour répondre à vos besoins spécifiques. Certaines des options les plus utiles incluent :

• Adaptateurs de Journal de Modifications personnalisés : Vous pouvez créer vos propres adaptateurs de journal de modifications pour générer des journaux dans un format adapté à votre projet.
• Stratégies de Versionnement personnalisées : Vous pouvez définir vos propres stratégies de versionnement pour contrôler la façon dont les versions des packages sont mises à jour.
• Configuration spécifique aux Monorepos : Changesets fournit des options de configuration spécifiques pour la gestion des monorepos, telles que la possibilité de spécifier les packages à inclure dans une version.

Adaptateurs de Journal de Modifications personnalisés

L'adaptateur de journal de modifications par défaut utilise le format Markdown, ce qui convient à la plupart des projets. Cependant, si vous avez besoin de générer des journaux de modifications dans un autre format, vous pouvez créer votre propre adaptateur personnalisé. Un adaptateur personnalisé est simplement un module JavaScript qui exporte une fonction qui prend un objet "changeset" en entrée et retourne une chaîne de caractères contenant l'entrée du journal de modifications. Voici un exemple :

            // my-custom-changelog-adapter.js
module.exports = async function getReleaseLine(changeset, versionType, options) {
  if (changeset.commit) {
    return `- ${changeset.summary} (commit: ${changeset.commit})
`;
  } else {
    return `- ${changeset.summary}
`;
  }
};

            

              
                Copy
              
            
          

Pour utiliser votre adaptateur personnalisé, vous devez mettre à jour l'option `changelog` dans le fichier `config.json` :

            {
  "changelog": "./my-custom-changelog-adapter.js",
  ...
}
            

              
                Copy
              
            
          

Stratégies de Versionnement personnalisées

Changesets utilise par défaut une stratégie de versionnement sémantique (SemVer), ce qui signifie que les versions des packages sont mises à jour en fonction du type de changements apportés (par exemple, majeure, mineure, corrective). Cependant, vous pouvez définir vos propres stratégies de versionnement pour contrôler la façon dont les versions des packages sont mises à jour. Ceci est utile si vous avez des exigences de versionnement spécifiques ou si vous souhaitez utiliser un schéma de versionnement différent.

Pour définir une stratégie de versionnement personnalisée, vous devez créer un module JavaScript qui exporte une fonction qui prend un objet "changeset" en entrée et retourne le type de mise à jour de version (par exemple, `major`, `minor`, `patch`). Voici un exemple :

            // my-custom-versioning-strategy.js
module.exports = async function determineVersion(changeset, options) {
  if (changeset.summary.includes("breaking change")) {
    return "major";
  } else if (changeset.summary.includes("feature")) {
    return "minor";
  } else {
    return "patch";
  }
};

            

              
                Copy
              
            
          

Actuellement, les stratégies de versionnement personnalisées nécessitent une configuration plus approfondie et ne sont pas directement prises en charge via `config.json`. Il s'agit d'un cas d'utilisation avancé et implique généralement la personnalisation du flux de travail Changesets à un niveau inférieur.

Meilleures Pratiques pour l'utilisation des "Changesets" Frontend

Pour maximiser les avantages de Frontend Changesets, suivez ces meilleures pratiques :

• Rédigez des descriptions de "changeset" claires et concises : La description du "changeset" est la partie la plus importante du "changeset". Assurez-vous de rédiger des descriptions claires, concises et informatives qui expliquent le but et l'impact des changements.
• Utilisez le versionnement sémantique : Suivez les principes du versionnement sémantique pour déterminer la mise à jour de version appropriée pour chaque package. Cela aidera à garantir que les utilisateurs de vos packages peuvent facilement comprendre l'impact de chaque version.
• Automatisez le processus de publication : Intégrez Changesets à votre pipeline CI/CD pour automatiser le processus de publication. Cela réduira le risque d'erreurs humaines et garantira un versionnement cohérent sur tous les packages.
• Examinez attentivement les "changesets" : Examinez attentivement les "changesets" avant de les fusionner dans la branche principale. Cela aidera à détecter les erreurs et à garantir que les changements sont correctement documentés.
• Gardez les "changesets" petits et ciblés : Visez des "changesets" petits et ciblés qui traitent un seul problème ou une seule fonctionnalité. Cela rendra plus facile la compréhension et la révision des changements.

Exemples Concrets

De nombreuses bibliothèques et frameworks JavaScript populaires utilisent Frontend Changesets pour gérer le versionnement et les publications. Voici quelques exemples :

• React Aria : Une bibliothèque de composants React pour construire des interfaces utilisateur accessibles.
• Reach UI : Une bibliothèque de primitives UI accessibles pour React.
• De nombreux autres projets open-source : De nombreux autres projets tirent parti de Changesets pour son processus de publication simplifié et ses fonctionnalités de collaboration améliorées.

Ces projets ont adopté avec succès Changesets pour améliorer leur processus de publication, renforcer la collaboration et maintenir un enregistrement transparent des changements. Leurs expériences démontrent la valeur et la polyvalence de cet outil puissant.

Dépannage des problèmes courants

Bien que Changesets soit généralement simple à utiliser, vous pourriez rencontrer quelques problèmes courants. Voici quelques conseils de dépannage :

• `No changesets found` : Cette erreur indique généralement que vous n'avez créé aucun "changeset" ou que Changesets n'est pas configuré correctement. Assurez-vous d'avoir créé au moins un "changeset" et que le fichier `config.json` est correctement configuré.
• `Version conflict` : Cette erreur se produit lorsque deux "changesets" ou plus spécifient des mises à jour de version conflictuelles pour le même package. Examinez les "changesets" et assurez-vous qu'ils sont cohérents.
• `Publish failed` : Cette erreur peut survenir pour diverses raisons, telles que des identifiants npm incorrects ou des problèmes de connectivité réseau. Vérifiez vos identifiants npm et assurez-vous d'avoir une connexion Internet stable.
• Problèmes d'intégration CI/CD : Examinez attentivement votre configuration CI/CD, en vous assurant que les variables d'environnement nécessaires (par exemple, `GITHUB_TOKEN`, `NPM_TOKEN`) sont correctement définies et que les commandes Changesets sont exécutées dans le bon ordre.

Si vous rencontrez d'autres problèmes, consultez la documentation officielle de Changesets ou demandez de l'aide à la communauté Changesets.

Conclusion

Frontend Changesets offre une solution puissante et flexible pour gérer le versionnement et les publications dans les projets frontend. En automatisant le processus de publication, en rationalisant la collaboration et en améliorant la transparence, Changesets peut améliorer considérablement l'efficacité et la fiabilité de votre flux de travail de développement. Que vous travailliez sur un petit projet personnel ou sur une application d'entreprise à grande échelle, Changesets peut vous aider à gérer votre code de manière plus efficace et à fournir des logiciels de haute qualité à vos utilisateurs.

En suivant les directives et les meilleures pratiques décrites dans ce guide, vous pouvez maîtriser Frontend Changesets et exploiter tout son potentiel pour améliorer votre flux de travail de développement frontend. Adoptez Changesets et prenez le contrôle de votre gestion de version dès aujourd'hui !