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 : 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. Semantische Veröffentlichung 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 Bei der nahtlosen Veröffentlichung in NPM stieß ich auf Hürden. Es war eine Herausforderung, die richtigen Konfigurationen sicherzustellen. öffentliches Paket 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 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. my_package_name 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 verwenden. Erstellen wir mit den Anfangsdaten. tokky package.json mkdir tokky && cd tokky && npm init -y Nach der Ausführung des Befehls generierte das System eine Standarddatei für das Projekt, die wie folgt aussieht: 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" } In diesem Handbuch spielt die Datei eine entscheidende Rolle bei der Sicherstellung der richtigen Konfiguration. An dieser Stelle geben wir die Knotenversion für unser Paket an: package.json echo "v18" > .nvmrc und aktivieren Sie die angegebene Version wie folgt: nvm use Für die Datei: README.md 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 ansprechen: package.json : Dies bezeichnet den primären Einstiegspunkt für das Modul. main : Hier geben Sie alle ausführbaren Dateien an, die Ihr Modul bereitstellt. bin : Dies sollte ein Array von Dateimustern enthalten, die beim Packen des Pakets und anschließender Veröffentlichung in der npm-Registrierung einbezogen werden. files : Stellen Sie sicher, dass dies auf gesetzt ist, da unser Paket öffentlich sein soll. private false : Der Zugriff hierfür sollte auf gesetzt sein. publishConfig public Nach diesen Konfigurationen sollte Ihre wie folgt aussehen: 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 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 git@github.com:<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 Ordner eine Datei und füllen Sie sie mit dem folgenden Inhalt: 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}`); } Einfaches Skript für ein Paketbeispiel Das Konzept ist einfach: Wenn Sie ausführen, sollte „Hallo [Benutzername]“ angezeigt werden. my_package_name hi 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 Ordner erstellt, der eine minimierte Datei enthält. dist index.js Token „Semantische Veröffentlichung ausführen“, die Versionssprünge ermittelt und den Veröffentlichungsprozess basierend auf Festschreibungsnachrichten abwickelt, erfordert Umgebungsvariablen ( , ), um ordnungsgemäß zu funktionieren. Die Token werden aus GitHub-Geheimnissen abgerufen, um sicherzustellen, dass sie vertraulich bleiben. GITHUB_TOKEN NPM_TOKEN Um festzulegen, navigieren Sie hier: GITHUB_TOKEN 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 zu generieren, benötigen Sie zunächst ein Konto . Wenn Sie noch nicht registriert sind, führen Sie den Registrierungsprozess durch. Navigieren Sie anschließend zu: NPM_TOKEN npms offizielle Website 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 zu den Repository-Geheimnissen hinzu: NPM_TOKEN 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 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. CI/CD- Erstellen Sie zunächst ein Verzeichnis im Stammverzeichnis Ihres Projekts. Richten Sie in diesem Verzeichnis einen Unterordner ein. .github workflows Erstellen Sie hier unsere Konfigurationsdatei mit dem Namen und füllen Sie sie mit dem folgenden Inhalt: 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 }} 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 mithilfe der angegebenen Token aufrufen. npm run semantic-release 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 und führen Sie es in Ihrem Repository aus: dieser GitHub-Code 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 , das wir zuvor in den Repository-Geheimnissen eingerichtet haben. Wenn Sie jetzt Ihre überprüfen, wird die Version wie folgt angezeigt: NPM_TOKEN package.json "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 Feld in Ihrer . Dieses Feld bietet Details zum Speicherort des Quellcodes des Pakets. repository package.json "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 den folgenden Inhalt enthält: 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 Für das Setup-Commit-Format-Tool werden wir verwenden . Um es zu installieren, befolgen Sie diesen Befehl: verpflichten npx commitizen init cz-conventional-changelog --save-dev --save-exact Dieser Befehl dauert einige Minuten. Aktualisieren Sie dann Ihre mit einem neuen Skript: package.json "scripts": { // ... "commit": "cz" }, und es ist Zeit, dieses Skript zu nutzen. Beginnen Sie mit der Ausführung von , führen Sie dann aus und geben Sie die erforderlichen Details für Ihr Commit an. git add . npm run commit 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 aus. git push 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 Navigieren Sie zu und konfigurieren Sie die Berechtigungen, um GitHub-Aktionen sowohl Lese- als auch Schreibzugriff zu ermöglichen. Ein entscheidender Schritt, der in den meisten Referenzen oft übersehen wird, ist das Festlegen der Workflow-Berechtigungen. https://github.com/<your_user_name>/tokky/settings/actions Lassen Sie uns als Nächstes die Dinge ein wenig ändern. Bestätigen Sie mit einem bestimmten Schlüsselwort, , gefolgt von Ihrer Nachricht. feat: git add . && git commit -m "feat: my feature commit" && git push Erinnern Sie sich an die in ? 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 , , 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. releaseRules package.json feat fix refactor 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 und schauen Sie im Abschnitt „Pakete“ nach. dort finden Sie Ihr neu veröffentlichtes Paket. https://www.npmjs.com/settings/<your_user_name>/packages Jetzt können Sie mit einem einfachen Befehl wie sofort die Ergebnisse unserer Entwicklungstests sehen. Darüber hinaus kann das Paket mit dem Befehl global installiert werden. npx your_package_name hi npm i -g your_package_name 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 als auch die entsprechenden Berechtigungen in GitHub Actions erhalten. Darüber hinaus sollte Ihre mit den Einstellungen für Zugriff korrekt konfiguriert sein und sicherstellen, dass die Konfiguration auf gesetzt ist. Wenn Sie auf Probleme stoßen oder Erkenntnisse haben, zögern Sie bitte nicht, einen Kommentar abzugeben. NPM_TOKEN GITHUB_TOKEN package.json publishConfig private false Verweise Repository: Semantische Release-CLI: Beauftragen: https://github.com/antonkalik/tokky https://github.com/semantic-release/cli https://github.com/commitizen/cz-cli Auch veröffentlicht. hier Dank an Harper Sonntag von Unsplash für das Hauptbild.
