So implementieren Sie die semantische Freigabe für öffentliche Pakete ohne Gültigkeitsbereich

Detaillierte Anweisungen zum Veröffentlichen eines öffentlichen Pakets ohne Gültigkeitsbereich mithilfe der semantischen Freigabe unter Nutzung der Leistungsfähigkeit von GitHub Actions

In der sich weiterentwickelnden Softwareentwicklungslandschaft ist die Wahrung der Versionskonsistenz und die Automatisierung des Release-Prozesses wichtiger denn je. Eingeben Semantische Veröffentlichung : ein Tool zur Gewährleistung einer klaren und strukturierten Versionierung. Für Entwickler, die öffentliche Pakete ohne Gültigkeitsbereich nutzen, kann der Prozess entmutigend wirken. Mit der Leistungsfähigkeit der GitHub-Aktionen, die uns zur Verfügung stehen, wird die Automatisierung jedoch zum Kinderspiel.

Dieser Artikel bietet eine detaillierte und umfassende Anleitung mit Schritt-für-Schritt-Anleitungen zur nahtlosen Integration von Semantic Release in Ihren Workflow, die speziell auf diejenigen zugeschnitten ist, die öffentliche Pakete ohne Gültigkeitsbereich verwenden. Tauchen Sie ein und entdecken Sie den optimierten Ansatz für Software-Releases.

Als ich meine erstellt habe öffentliches Paket Bei der nahtlosen Veröffentlichung in NPM stieß ich auf Hürden. Es war eine Herausforderung, die richtigen Konfigurationen sicherzustellen.

Um es auf den Punkt zu bringen, gehen wir eine Schritt-für-Schritt-Anleitung für die ordnungsgemäße Veröffentlichung öffentlicher Pakete durch NPM .

Inhaltsübersicht

• Benennen Sie das Paket
• Erstellen Sie ein Paket
• Paketquelle
• Token
• Einrichtung der GitHub-Aktionen
• Semantische Veröffentlichung
• Commit-Format
• Veröffentlichtes Paket
• Abschluss

Benennen Sie das Paket

Bevor Sie mit der Implementierung unseres Pakets beginnen, ist es besser, den richtigen Namen dafür zu finden. Um sicherzustellen, dass der Name nicht bereits vergeben ist, überprüfen Sie my_package_name und übernehmen Sie ihn für Ihr Paket. Ich habe „tokky“ gewählt. Ab diesem Zeitpunkt ist eine Reservierung des Paketnamens nicht mehr möglich. Für den Namen in npm müssen Sie das Paket veröffentlichen.

Erstellen Sie ein Paket

Ziel ist es, ein unkompliziertes Paket zu entwickeln, das Inhalte auf der Konsole ausgibt. Wir müssen sicherstellen, dass wir es installieren und ausführen können. Für den Build-Prozess verwenden wir einfach esbuild .

In diesem Artikel werde ich den Namen des Pakets tokky verwenden. Erstellen wir package.json mit den Anfangsdaten.

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

Nach der Ausführung des Befehls generierte das System eine Standarddatei package.json für das Projekt, die wie folgt aussieht:

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

In diesem Handbuch spielt die Datei package.json eine entscheidende Rolle bei der Sicherstellung der richtigen Konfiguration. An dieser Stelle geben wir die Knotenversion für unser Paket an:

 echo "v18" > .nvmrc

und aktivieren Sie die angegebene Version wie folgt:

 nvm use

Für die README.md Datei:

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

Installieren Sie abschließend die Entwicklungsabhängigkeiten:

 npm i -D esbuild eslint prettier

In unserer Erstkonfiguration müssen wir mehrere wichtige Punkte in package.json ansprechen:

• main : Dies bezeichnet den primären Einstiegspunkt für das Modul.
• bin : Hier geben Sie alle ausführbaren Dateien an, die Ihr Modul bereitstellt.
• files : Dies sollte ein Array von Dateimustern enthalten, die beim Packen des Pakets und anschließender Veröffentlichung in der npm-Registrierung einbezogen werden.
• private : Stellen Sie sicher, dass dies auf false gesetzt ist, da unser Paket öffentlich sein soll.
• publishConfig : Der Zugriff hierfür sollte auf public gesetzt sein.

Nach diesen Konfigurationen sollte Ihre package.json wie folgt aussehen:

 { "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 nach der Ersteinrichtung

Fügen wir außerdem zwei Ignorierdateien hinzu:

 .idea node_modules dist

.gitignore

und für npm:

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

.npmignore

Abschließend werde ich mein Setup für ESLint skizzieren. Bedenken Sie jedoch, dass die Konfiguration je nach den spezifischen Anforderungen Ihres Pakets variieren kann.

 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: {}, };

.eslintrc.js-Konfiguration

Gehen Sie als Nächstes zu GitHub und richten Sie ein neues Repository ein. Benennen Sie es nach Ihrem Paket.

Fahren Sie fort, indem Sie die folgenden Befehle ausführen:

 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

Paketquelle

Als Nächstes erstellen wir eine Basisanwendung und richten sie für die Erstellung ein. Generieren Sie im src Ordner eine index.js Datei und füllen Sie sie mit dem folgenden Inhalt:

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

Einfaches Skript für ein Paketbeispiel

Das Konzept ist einfach: Wenn Sie my_package_name hi ausführen, sollte „Hallo [Benutzername]“ angezeigt werden.

Um diese Funktionalität zu validieren, führen Sie den Befehl direkt aus Ihrem Repository aus, indem Sie Folgendes verwenden:

 node src/index.js hi

Wenn die Ausgabe den Erwartungen entspricht, ist es an der Zeit, die Quelle zu erstellen:

 npm run build

Bei erfolgreicher Ausführung dieses Befehls wird ein dist Ordner erstellt, der eine minimierte index.js Datei enthält.

Token

„Semantische Veröffentlichung ausführen“, die Versionssprünge ermittelt und den Veröffentlichungsprozess basierend auf Festschreibungsnachrichten abwickelt, erfordert Umgebungsvariablen ( GITHUB_TOKEN , NPM_TOKEN ), um ordnungsgemäß zu funktionieren. Die Token werden aus GitHub-Geheimnissen abgerufen, um sicherzustellen, dass sie vertraulich bleiben.

Um GITHUB_TOKEN festzulegen, navigieren Sie hier: https://github.com/settings/tokens

Generieren Sie das Token mithilfe eines Dropdown-Menüs. Klicken Sie auf das neue persönliche Zugriffstoken (klassisch) und legen Sie die Berechtigung wie im Bild fest.

Verwenden Sie Ihren Paketnamen wie unten gezeigt:

Kopieren Sie nach der Generierung den Token-Wert und bewahren Sie ihn vertraulich auf – es ist wichtig, ihn nicht an andere weiterzugeben. Bewahren Sie dieses Token vorübergehend sicher auf, da wir es in Kürze für die Semantic Release CLI benötigen.

Um das NPM_TOKEN zu generieren, benötigen Sie zunächst ein Konto npms offizielle Website . Wenn Sie noch nicht registriert sind, führen Sie den Registrierungsprozess durch. Navigieren Sie anschließend zu:

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

und generieren Sie einen „klassischen“ Token mit der Option „Veröffentlichen“.

Kopieren Sie den generierten Wert des Tokens und navigieren Sie zu den GitHub-Geheimnissen:

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

und fügen Sie das neue Geheimnis als NPM_TOKEN zu den Repository-Geheimnissen hinzu:

Nachdem unsere Geheimnisse nun eingerichtet sind, können wir GitHub-Aktionen konfigurieren.

Einrichtung der GitHub-Aktionen

Um unsere Prozesse zu automatisieren, werden wir GitHub Actions verwenden. Dies ist ein in GitHub integriertes CI/CD- Tool. Damit können Entwickler Arbeitsabläufe direkt aus ihren GitHub-Repositorys automatisieren, beispielsweise das Erstellen, Testen und Bereitstellen von Anwendungen. Durch die Definition von Workflows in YAML-Dateien können Benutzer Aktionen basierend auf bestimmten Ereignissen wie Push- und Pull-Anfragen oder geplanten Zeiten auslösen, wodurch der Softwareentwicklungsprozess effizienter und automatisierter wird.

Erstellen Sie zunächst ein .github Verzeichnis im Stammverzeichnis Ihres Projekts. Richten Sie in diesem Verzeichnis einen Unterordner workflows ein.

Erstellen Sie hier unsere Konfigurationsdatei mit dem Namen release.yml und füllen Sie sie mit dem folgenden Inhalt:

 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 }}

Dieser Workflow löst ein Push-Ereignis an den Hauptzweig aus. Es ist so konfiguriert, dass der Job auf der neuesten virtuellen Ubuntu-Maschine ausgeführt wird, die GitHub anbietet. Obwohl es nicht zwingend erforderlich ist, sich mit jedem Job auseinanderzusetzen, wollen wir einige spezifische hervorheben. Beachten Sie gegen Ende, wie wir npm run semantic-release mithilfe der angegebenen Token aufrufen.

Semantische Veröffentlichung

Für den automatisierten Release-Prozess werden wir Semantic Release verwenden. Dieses Tool übernimmt die Versionierung und Paketveröffentlichung basierend auf der Commit-Nachrichtensemantik. Es folgt den Konventionen der semantischen Versionierung (SemVer), um Versionssprünge (Hauptversion, Nebenversion oder Patch) zu bestimmen. Durch die Analyse von Commit-Nachrichten entfallen die manuellen Schritte der Versionierung, es werden konsistente Versionsnummern sichergestellt und der Release-Prozess optimiert. Lass es uns einrichten.

Für dieses Setup verwenden wir dieser GitHub-Code und führen Sie es in Ihrem Repository aus:

 npx semantic-release-cli setup

Und folgen Sie den Fragen:

 % 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

Sie sollten bereits über Ihren persönlichen Token verfügen. Geben Sie es einfach ein, wenn Sie dazu aufgefordert werden. Ebenso nutzen die von uns eingerichteten GitHub-Aktionen das NPM_TOKEN , das wir zuvor in den Repository-Geheimnissen eingerichtet haben. Wenn Sie jetzt Ihre package.json überprüfen, wird die Version wie folgt angezeigt:

 "version": "0.0.0-development",

und neues Skript:

 "semantic-release": "semantic-release"

die von der Semantic Release CLI automatisch generiert wurde. Wir müssen dieses Skript wie folgt erweitern:

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

Dies weist darauf hin, dass Veröffentlichungen nur aus dem Hauptzweig erfolgen.

Darüber hinaus generiert Semantic Release eine Beschreibung basierend auf dem repository Feld in Ihrer package.json . Dieses Feld bietet Details zum Speicherort des Quellcodes des Pakets.

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

Lassen Sie uns nun alle unsere Änderungen vorantreiben mit:

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

Commit-Format

Semantic Release basiert auf der Konvention strukturierter Commit-Nachrichten, um die Art der Versionserhöhung (Hauptversion, Nebenversion oder Patch) zu bestimmen und Änderungsprotokolle zu generieren. Diese Commit-Konvention wird oft als „Konventionelle Commits“-Format bezeichnet.

Für diese Konfiguration benötigen wir mehrere Plugins. Stellen Sie sicher, dass Ihre package.json den folgenden Inhalt enthält:

 "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

Für das Setup-Commit-Format-Tool werden wir verwenden verpflichten . Um es zu installieren, befolgen Sie diesen Befehl:

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

Dieser Befehl dauert einige Minuten. Aktualisieren Sie dann Ihre package.json mit einem neuen Skript:

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

und es ist Zeit, dieses Skript zu nutzen. Beginnen Sie mit der Ausführung von git add . , führen Sie dann npm run commit aus und geben Sie die erforderlichen Details für Ihr Commit an.

So sieht das aus:

 ? 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

Führen Sie danach einen git push aus.

In den GitHub-Aktionen sehen Sie, dass unser Commit fehlgeschlagen ist, weil wir die restlichen Pakete für den automatisierten Commit-Nachrichtenprozess noch nicht installiert haben.

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

Ein entscheidender Schritt, der in den meisten Referenzen oft übersehen wird, ist das Festlegen der Workflow-Berechtigungen. Navigieren Sie zu https://github.com/<your_user_name>/tokky/settings/actions und konfigurieren Sie die Berechtigungen, um GitHub-Aktionen sowohl Lese- als auch Schreibzugriff zu ermöglichen.

Lassen Sie uns als Nächstes die Dinge ein wenig ändern. Bestätigen Sie mit einem bestimmten Schlüsselwort, feat: , gefolgt von Ihrer Nachricht.

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

Erinnern Sie sich an die releaseRules in package.json ? Diese Regeln bestimmen, wie wir die Version unserer Paketversion erhöhen. Wenn dies eingerichtet ist, können Sie eine Pull-Anfrage mit bestimmten Schlüsselwörtern wie feat , fix , refactor usw. erstellen. Sobald dieser Pull-Request genehmigt und anschließend in den Hauptzweig eingebunden wird, wird ein Trigger ausgelöst. Dieser Auslöser aktiviert dann die GitHub-Aktion, automatisiert den Veröffentlichungsprozess und stellt sicher, dass Ihr Paket nahtlos aktualisiert wird.

Veröffentlichtes Paket

Das Paket wurde erfolgreich veröffentlicht und der gesamte Prozess wurde aus Effizienzgründen automatisiert. Um die Veröffentlichung zu bestätigen, gehen Sie zu Ihren NPM-Einstellungen https://www.npmjs.com/settings/<your_user_name>/packages und schauen Sie im Abschnitt „Pakete“ nach. dort finden Sie Ihr neu veröffentlichtes Paket.

Jetzt können Sie mit einem einfachen Befehl wie npx your_package_name hi sofort die Ergebnisse unserer Entwicklungstests sehen. Darüber hinaus kann das Paket mit dem Befehl npm i -g your_package_name global installiert werden.

Abschluss

Wie wir in diesem Artikel gesehen haben, können anfängliche Setups zwar voller Herausforderungen sein, die Belohnung liegt jedoch in der Einrichtung eines optimierten und konsistenten Release-Prozesses. Die Nutzung von GitHub Actions vereinfacht diese Komplexität und stellt sicher, dass sich Entwickler auf die Codequalität und nicht auf logistische Feinheiten konzentrieren können.

Unabhängig davon, ob Sie gerade erst mit öffentlichen Paketen beginnen oder bei Ihren Veröffentlichungsbemühungen auf Rückschläge gestoßen sind, ist die Einführung eines strukturierten, automatisierten Workflows unbestreitbar wertvoll. Durch die Integration von Semantic Release stellen Sie eine konsistente Versionierung sicher und fördern einen zukunftsorientierten Ansatz bei der Softwareentwicklung.

Auf eine nahtlose Veröffentlichung, weniger Kopfschmerzen und mehr Zeit für die Perfektionierung des Codes, der unsere digitale Welt vorantreibt.

Denken Sie daran, dass es wichtig ist, dass sowohl NPM_TOKEN als auch GITHUB_TOKEN die entsprechenden Berechtigungen in GitHub Actions erhalten. Darüber hinaus sollte Ihre package.json mit den Einstellungen für publishConfig Zugriff korrekt konfiguriert sein und sicherstellen, dass die private Konfiguration auf false gesetzt ist. Wenn Sie auf Probleme stoßen oder Erkenntnisse haben, zögern Sie bitte nicht, einen Kommentar abzugeben.

Verweise

Repository: https://github.com/antonkalik/tokky
Semantische Release-CLI: https://github.com/semantic-release/cli
Beauftragen: https://github.com/commitizen/cz-cli