Comment implémenter la libération sémantique pour les packages publics sans portée

Instructions détaillées sur la publication d'un package public sans portée à l'aide d'une version sémantique tirant parti de la puissance des actions GitHub

Dans le paysage du développement logiciel en évolution, maintenir la cohérence des versions et automatiser le processus de publication est plus important que jamais. Entrer Libération sémantique : un outil conçu pour assurer un versioning clair et structuré. Pour les développeurs qui exploitent des packages publics sans portée, le processus peut sembler intimidant. Cependant, avec la puissance des actions GitHub à portée de main, l’automatisation devient un jeu d’enfant.

Cet article propose un guide détaillé et complet, fournissant des instructions étape par étape pour intégrer de manière transparente Semantic Release dans votre flux de travail, spécialement adapté à ceux qui utilisent des packages publics sans portée. Plongez et découvrez l'approche rationalisée des versions logicielles.

Quand j'ai créé mon forfait public , j'ai rencontré des obstacles pour le publier de manière transparente sur NPM. C'était un défi de garantir les bonnes configurations.

Pour y parvenir, passons en revue une expérience étape par étape pour la publication appropriée de packages publics vers MNP .

Aperçu du contenu

• Nommez le paquet
• Créer un forfait
• Source du paquet
• Jetons
• Configuration des actions GitHub
• Libération sémantique
• Format de validation
• Package publié
• Conclusion

Nommez le paquet

Avant de se lancer dans l’implémentation de notre package, il est préférable de lui trouver le nom approprié. Pour être sûr que le nom n'est pas déjà pris, vérifiez my_package_name et prenez-le pour votre package. J'ai choisi "tokky". A partir de ce moment, réserver le nom du package est impossible. Pour le nom en npm, vous devez publier le package.

Créer un forfait

L'objectif est de développer un package simple qui affiche du contenu sur la console. Nous devons nous assurer que nous pouvons l'installer et l'exécuter. Pour le processus de construction, utilisons simple esconstruire .

Au cours de cet article, j'utiliserai le nom du package tokky . Créons package.json avec les données initiales.

 mkdir tokky && cd tokky && npm init -y

Après avoir exécuté la commande, le système a généré un fichier package.json par défaut pour le projet, qui ressemble à ceci :

 { "name": "tokky", "version": "1.0.0", "description": "", "main": "index.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "keywords": [], "author": "", "license": "ISC" }

Dans ce guide, le fichier package.json joue un rôle crucial pour garantir la bonne configuration. À ce stade, spécifions la version du nœud pour notre package :

 echo "v18" > .nvmrc

et activez la version spécifiée avec ce qui suit :

 nvm use

Pour le fichier README.md :

 echo "# Tokky\n\nA simple zero dependency logger for node js." > README.md

Enfin, installez les dépendances de développement :

 npm i -D esbuild eslint prettier

Dans notre configuration initiale, nous devons aborder plusieurs points clés dans le package.json :

• main : Ceci désigne le point d’entrée principal du module.
• bin : Ici, vous spécifierez tous les exécutables fournis par votre module.
• files : cela doit contenir un tableau de modèles de fichiers qui seront inclus lorsque le package sera compressé et ensuite publié dans le registre npm.
• private : assurez-vous que cette valeur est définie sur false car notre package est destiné à être public.
• publishConfig : l'accès pour cela doit être défini sur public .

Après ces configurations, votre package.json devrait ressembler à ce qui suit :

 { "name": "tokky", "version": "1.0.0", "description": "Node js logger package", "main": "dist/index.js", "scripts": { "build": "esbuild src/index.js --bundle --platform=node --format=cjs --minify --outfile=dist/index.js", }, "files": [ "dist" ], "bin": { "tokky": "./dist/index.js" }, "keywords": [ "logger", "nodejs", "tokky" ], "private": false, "author": { "name": "Anton Kalik", "email": "[email protected]", "url": "https://idedy.com" }, "publishConfig": { "access": "public" }, "license": "MIT", "engines": { "node": "18.xx" }, "devDependencies": { "esbuild": "^0.19.2", "eslint": "^8.49.0", "prettier": "^3.0.3" } }

package.json après la configuration initiale

De plus, ajoutons deux fichiers ignorés :

 .idea node_modules dist

.gitignore

et pour npm :

 .idea /src/ /node_modules/ /test/ /.nvmrc .github/

.npmignore

Enfin, je décrirai ma configuration pour ESLint. N'oubliez cependant pas que la configuration peut varier en fonction des exigences spécifiques de votre forfait.

 module.exports = { env: { browser: true, commonjs: true, es2021: true, node: true, }, extends: "eslint:recommended", overrides: [ { env: { node: true, }, files: ["src/**/*.js", ".eslintrc.{js,cjs}"], parserOptions: { sourceType: "script", }, }, ], parserOptions: { ecmaVersion: "latest", }, rules: {}, };

Configuration .eslintrc.js

Ensuite, dirigez-vous vers GitHub et créez un nouveau référentiel. Nommez-le d'après votre colis.

Continuez en exécutant les commandes suivantes :

 git init git add . git commit -m "first commit" git branch -M main git remote add origin [email protected]:<your_github_username>/tokky.git git push -u origin main

Source du paquet

Ensuite, créons une application de base et configurons-la pour la construction. Dans le dossier src , générez un fichier index.js et remplissez-le avec le contenu suivant :

 #!/usr/bin/env node const os = require('os'); const username = os.userInfo().username; if (process.argv[2] === 'hi') { console.log(`Hello ${username}`); }

Script simple pour un exemple de package

Le concept est simple : l'exécution my_package_name hi devrait afficher "Bonjour [nom d'utilisateur]".

Pour valider cette fonctionnalité, exécutez la commande directement depuis votre référentiel en utilisant :

 node src/index.js hi

Si le résultat correspond aux attentes, il est temps de créer la source :

 npm run build

L'exécution réussie de cette commande produira un dossier dist contenant un fichier index.js minifié.

Jetons

Exécuter Semantic Release, qui déterminera les changements de version et gérera le processus de publication en fonction des messages de validation, nécessite des variables d'environnement ( GITHUB_TOKEN , NPM_TOKEN ) pour fonctionner correctement. Les jetons sont extraits des secrets de GitHub, garantissant ainsi leur confidentialité.

Pour définir GITHUB_TOKEN , naviguez ici : https://github.com/settings/tokens

Générez le jeton à l'aide d'une liste déroulante. Cliquez sur le nouveau jeton d'accès personnel (classique) et définissez l'autorisation comme sur l'image.

Utilisez le nom de votre package comme indiqué ci-dessous :

Une fois généré, copiez la valeur du jeton et gardez-la confidentielle : il est crucial de ne pas la partager avec d'autres. Stockez temporairement ce jeton en toute sécurité, car nous en aurons bientôt besoin pour la CLI Semantic Release.

Pour générer le NPM_TOKEN , vous avez d'abord besoin d'un compte sur site officiel de npm . Si vous n'êtes pas encore inscrit, suivez le processus d'inscription. Après cela, accédez à :

 https://www.npmjs.com/settings/<your_user_name>/tokens/new

et générez un token « classique » avec l’option « publier ».

Copiez la valeur générée du jeton et accédez aux secrets GitHub :

 https://github.com/<your_user_name>/<your_repo_name>/settings/secrets/actions/new

et mettez le nouveau secret sous le nom NPM_TOKEN dans les secrets du référentiel :

Une fois nos secrets configurés, nous pouvons configurer les actions GitHub.

Configuration des actions GitHub

Pour automatiser nos processus, nous allons utiliser GitHub Actions. Il s'agit d'un outil CI/CD intégré à GitHub. Il permet aux développeurs d'automatiser les flux de travail directement à partir de leurs référentiels GitHub, tels que la création, les tests et le déploiement d'applications. En définissant des flux de travail dans des fichiers YAML, les utilisateurs peuvent déclencher des actions basées sur des événements spécifiques tels que des demandes push et pull ou des heures planifiées, rendant ainsi le processus de développement logiciel plus efficace et automatisé.

Pour commencer, créez un répertoire .github à la racine de votre projet. Dans ce répertoire, créez un sous-dossier workflows .

Ici, créez notre fichier de configuration nommé release.yml et remplissez-le avec le contenu suivant :

 name: Release package on: push: branches: - main jobs: release: runs-on: ubuntu-latest if: ${{ github.ref == 'refs/heads/main' }} steps: - name: Checkout uses: actions/checkout@v3 - name: Set up Node.js uses: actions/setup-node@v3 with: node-version: "18" - name: Install dependencies run: npm ci - name: Build run: npm run build - name: Semantic Release run: npm run semantic-release env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Ce workflow déclenche un événement push vers la branche principale. Il est configuré pour exécuter le travail sur les dernières offres de machine virtuelle Ubuntu GitHub. Même s’il n’est pas impératif d’examiner chaque emploi, mettons-en en lumière quelques-uns en particulier. Vers la fin, notez comment nous invoquons npm run semantic-release en utilisant les jetons désignés.

Libération sémantique

Pour le processus de publication automatisé, nous allons utiliser Semantic Release. Cet outil gère la gestion des versions et la publication des packages en fonction de la sémantique des messages de validation. Il suit les conventions du Semantic Versioning (SemVer) pour déterminer les changements de version (majeurs, mineurs ou correctifs). En analysant les messages de validation, il élimine les étapes manuelles de gestion des versions, garantit des numéros de version cohérents et rationalise le processus de publication. Installons-le.

Pour cette configuration, nous utiliserons ce code GitHub et exécutez-le sur votre référentiel :

 npx semantic-release-cli setup

Et suivez les questions :

 % npx semantic-release-cli setup ? What is your npm registry? https://registry.npmjs.org/ ? What is your npm username? your_user_name ? What is your npm password? [hidden] ? What is your NPM two-factor authentication code? 00000000 ? Provide a GitHub Personal Access Token (create a token at https://github.com/s ettings/tokens/new?scopes=repo) ghp_your_token_here ? What CI are you using? Github Actions

Vous devriez déjà avoir votre jeton personnel. Saisissez-le simplement lorsque vous y êtes invité. De même, les actions GitHub que nous avons mises en place utiliseront le NPM_TOKEN que nous avons précédemment établi dans les secrets du référentiel. Si vous vérifiez maintenant votre package.json , la version s'affichera comme suit :

 "version": "0.0.0-development",

et nouveau script :

 "semantic-release": "semantic-release"

qui a été généré automatiquement par la CLI Semantic Release. Nous devrons améliorer ce script comme suit :

 "semantic-release": "semantic-release --branches main"

Cela indique que les versions seront effectuées uniquement à partir de la branche principale.

De plus, Semantic Release génère une description basée sur le champ repository dans votre package.json . Ce champ offre des détails sur l'emplacement du code source du package.

 "repository": { "type": "git", "url": "https://github.com/<your_github_username>/your_github_repo.git" }

Maintenant, poussons tous nos changements avec :

 git add . && git commit -m "semantic release" && git push

Format de validation

Semantic Release s'appuie sur la convention des messages de validation structurés pour déterminer le type de changement de version (majeur, mineur ou correctif) et générer des journaux de modifications. Cette convention de commit est souvent appelée format « Conventional Commits ».

Pour cette configuration, nous aurons besoin de plusieurs plugins. Assurez-vous que votre package.json contient le contenu suivant :

 "release": { "branches": [ { "name": "main" } ], "plugins": [ [ "@semantic-release/commit-analyzer", { "releaseRules": [ { "type": "feat", "release": "minor" }, { "type": "fix", "release": "patch" }, { "type": "refactor", "release": "patch" }, { "type": "build", "release": "patch" }, { "type": "chore", "release": "patch" }, { "type": "minor", "release": "patch" } ] } ], "@semantic-release/release-notes-generator", "@semantic-release/npm", "@semantic-release/github", [ "@semantic-release/changelog", { "changelogFile": "CHANGELOG.md" } ] ] }

package.json

Pour l'outil de format de validation de configuration, nous allons utiliser s'engager . Pour l'installer, suivez cette commande :

 npx commitizen init cz-conventional-changelog --save-dev --save-exact

Cette commande prendra quelques minutes. Mettez ensuite à jour votre package.json avec un nouveau script :

 "scripts": { // ... "commit": "cz" },

et il est temps d'utiliser ce script. Commencez par exécuter git add . , puis exécutez npm run commit et fournissez les détails nécessaires pour votre validation.

Voici à quoi cela ressemble :

 ? Select the type of change that you're committing: feat: A new feature ? What is the scope of this change (eg component or file name): (press enter to skip) commit ? Write a short, imperative tense description of the change (max 86 chars): (14) add commitizen ? Provide a longer description of the change: (press enter to skip) ? Are there any breaking changes? No ? Does this change affect any open issues? No

Après cela, faites un git push .

Dans les actions GitHub, vous verrez que notre validation a échoué car nous n'avons toujours pas installé le reste des packages pour le processus automatisé de message de validation.

 npm i -D @semantic-release/commit-analyzer @semantic-release/release-notes-generator @semantic-release/npm @semantic-release/changelog

Une étape cruciale, souvent négligée dans la plupart des références, consiste à définir les autorisations du flux de travail. Accédez à https://github.com/<your_user_name>/tokky/settings/actions et configurez les autorisations pour autoriser les actions GitHub à la fois en lecture et en écriture.

Ensuite, changeons un peu les choses. Engagez-vous avec un mot-clé spécifique, feat: , suivi de votre message.

 git add . && git commit -m "feat: my feature commit" && git push

Vous souvenez-vous des releaseRules dans le package.json ? Ces règles dictent la manière dont nous incrémentons la version de notre package. Une fois cela en place, vous pouvez créer une pull request en utilisant des mots-clés spécifiques tels que feat , fix , refactor , etc. Une fois cette demande d'extraction approuvée puis fusionnée dans la branche principale, elle lancera un déclencheur. Ce déclencheur active ensuite l'action GitHub, automatise le processus de publication et garantit que votre package est mis à jour de manière transparente.

Package publié

Le package a été publié avec succès et l’ensemble du processus a été automatisé pour plus d’efficacité. Pour confirmer la publication, accédez à vos paramètres npm https://www.npmjs.com/settings/<your_user_name>/packages et regardez sous la section packages ; là, vous trouverez votre package nouvellement publié.

Désormais, avec une simple commande comme npx your_package_name hi , vous pouvez immédiatement voir les résultats de nos tests de développement. De plus, le package peut être installé globalement à l'aide de la commande npm i -g your_package_name .

Conclusion

Comme nous l'avons vu tout au long de cet article, même si les configurations initiales peuvent être semées d'embûches, la récompense réside dans l'établissement d'un processus de publication rationalisé et cohérent. L'exploitation de GitHub Actions simplifie ces complexités, garantissant que les développeurs peuvent se concentrer sur la qualité du code plutôt que sur les subtilités logistiques.

Que vous commenciez tout juste votre parcours avec des packages publics ou que vous ayez rencontré des revers dans vos efforts de publication, l'adoption d'un flux de travail structuré et automatisé présente un intérêt indéniable. En intégrant Semantic Release, vous garantissez une gestion des versions cohérente et défendez une approche tournée vers l'avenir en matière de développement logiciel.

Voilà pour une publication transparente, moins de maux de tête et plus de temps passé à perfectionner le code qui fait avancer notre monde numérique.

N'oubliez pas qu'il est essentiel que NPM_TOKEN et GITHUB_TOKEN disposent des autorisations appropriées dans GitHub Actions. De plus, votre package.json doit être correctement configuré avec les paramètres d'accès publishConfig et assurez-vous que la configuration private est définie sur false . Si vous rencontrez des problèmes ou avez des idées, n'hésitez pas à commenter.

Les références

Dépôt: https://github.com/antonkalik/tokky
CLI de version sémantique : https://github.com/semantic-release/cli
S'engager : https://github.com/commitizen/cz-cli