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 : 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. Libération sémantique 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 , j'ai rencontré des obstacles pour le publier de manière transparente sur NPM. C'était un défi de garantir les bonnes configurations. forfait public 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 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. my_package_name 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 . Créons avec les données initiales. tokky package.json mkdir tokky && cd tokky && npm init -y Après avoir exécuté la commande, le système a généré un fichier par défaut pour le projet, qui ressemble à ceci : package.json { "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 joue un rôle crucial pour garantir la bonne configuration. À ce stade, spécifions la version du nœud pour notre package : package.json 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 : Ceci désigne le point d’entrée principal du module. main : Ici, vous spécifierez tous les exécutables fournis par votre module. bin : 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. files : assurez-vous que cette valeur est définie sur car notre package est destiné à être public. private false : l'accès pour cela doit être défini sur . publishConfig public Après ces configurations, votre devrait ressembler à ce qui suit : package.json { "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": "antonkalik@gmail.com", "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 git@github.com:<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 , générez un fichier et remplissez-le avec le contenu suivant : src index.js #!/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 devrait afficher "Bonjour [nom d'utilisateur]". my_package_name hi 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 contenant un fichier minifié. dist index.js 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 ( , ) pour fonctionner correctement. Les jetons sont extraits des secrets de GitHub, garantissant ainsi leur confidentialité. GITHUB_TOKEN NPM_TOKEN Pour définir , naviguez ici : GITHUB_TOKEN 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 , vous avez d'abord besoin d'un compte sur . Si vous n'êtes pas encore inscrit, suivez le processus d'inscription. Après cela, accédez à : NPM_TOKEN site officiel de npm 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 dans les secrets du référentiel : NPM_TOKEN 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 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é. CI/CD Pour commencer, créez un répertoire à la racine de votre projet. Dans ce répertoire, créez un sous-dossier . .github workflows Ici, créez notre fichier de configuration nommé et remplissez-le avec le contenu suivant : release.yml 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 en utilisant les jetons désignés. npm run semantic-release 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 et exécutez-le sur votre référentiel : ce code GitHub 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 que nous avons précédemment établi dans les secrets du référentiel. Si vous vérifiez maintenant votre , la version s'affichera comme suit : NPM_TOKEN package.json "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 dans votre . Ce champ offre des détails sur l'emplacement du code source du package. repository package.json "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 contient le contenu suivant : package.json "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 . Pour l'installer, suivez cette commande : s'engager npx commitizen init cz-conventional-changelog --save-dev --save-exact Cette commande prendra quelques minutes. Mettez ensuite à jour votre avec un nouveau script : package.json "scripts": { // ... "commit": "cz" }, et il est temps d'utiliser ce script. Commencez par exécuter , puis exécutez et fournissez les détails nécessaires pour votre validation. git add . npm run commit 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 Accédez à et configurez les autorisations pour autoriser les actions GitHub à la fois en lecture et en écriture. Une étape cruciale, souvent négligée dans la plupart des références, consiste à définir les autorisations du flux de travail. https://github.com/<your_user_name>/tokky/settings/actions Ensuite, changeons un peu les choses. Engagez-vous avec un mot-clé spécifique, , suivi de votre message. feat: git add . && git commit -m "feat: my feature commit" && git push Vous souvenez-vous des dans le ? 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 , , , 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. releaseRules package.json feat fix refactor 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 et regardez sous la section packages ; là, vous trouverez votre package nouvellement publié. https://www.npmjs.com/settings/<your_user_name>/packages Désormais, avec une simple commande comme , 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 . npx your_package_name hi 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 et disposent des autorisations appropriées dans GitHub Actions. De plus, votre doit être correctement configuré avec les paramètres d'accès et assurez-vous que la configuration est définie sur . Si vous rencontrez des problèmes ou avez des idées, n'hésitez pas à commenter. NPM_TOKEN GITHUB_TOKEN package.json publishConfig private false Les références Dépôt: CLI de version sémantique : S'engager : https://github.com/antonkalik/tokky https://github.com/semantic-release/cli https://github.com/commitizen/cz-cli Également publié . ici Grâce à Dimanche Harper à partir d'Unsplash pour l'image principale.
