スコープ指定されていないパブリック パッケージのセマンティック リリースを実装する方法

GitHub Actions の機能を活用したセマンティック リリースを使用してスコープ指定のないパブリック パッケージを公開するための詳細な手順

進化するソフトウェア開発環境では、バージョンの一貫性を維持し、リリース プロセスを自動化することがこれまで以上に重要になっています。入力セマンティックリリース: 明確で構造化されたバージョン管理を確保するために設計されたツール。パブリックのスコープ指定されていないパッケージを利用する開発者にとって、このプロセスは困難に思えるかもしれません。ただし、GitHub アクションを簡単に利用できるため、自動化は簡単になります。

この記事では、詳細かつ包括的なガイドを提供し、セマンティック リリースをワークフローにシームレスに統合するためのステップバイステップの手順を提供します。特に、スコープ指定されていないパブリック パッケージを使用するユーザー向けに調整されています。ソフトウェア リリースへの合理化されたアプローチを詳しく見てみましょう。

私が自分のものを作成したときパブリックパッケージ, NPM にシームレスに公開するにはハードルがありました。適切な構成を確保するのは困難でした。

それを成功させるために、公開パッケージを適切に公開するためのステップバイステップの体験をしてみましょう。故宮。

コンテンツの概要

• パッケージに名前を付けます
• パッケージを作成する
• パッケージソース
• トークン
• GitHub アクションのセットアップ
• セマンティックリリース
• コミット形式
• 公開されたパッケージ
• 結論

パッケージに名前を付けます

パッケージの実装に取り掛かる前に、パッケージの適切な名前を見つけておくことをお勧めします。名前がまだ使用されていないことを確認するには、 my_package_name確認し、それをパッケージに使用します。私は「トッキー」を選びました。その時点から、パッケージの名前を予約することはできなくなります。 npm での名前については、パッケージを公開する必要があります。

パッケージを作成する

目的は、コンテンツをコンソールに出力する簡単なパッケージを開発することです。インストールして実行できることを確認する必要があります。ビルドプロセスには、単純なものを使用しましょうエスビルド。

この記事では、パッケージ名をtokkyとして使用します。初期データを使用してpackage.jsonを作成しましょう。

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

コマンドを実行すると、システムはプロジェクトのデフォルトの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" }

このガイドでは、 package.jsonファイルが適切な構成を確保する上で重要な役割を果たします。この時点で、パッケージのノードのバージョンを指定しましょう。

 echo "v18" > .nvmrc

次のように指定したバージョンをアクティブ化します。

 nvm use

README.mdファイルの場合:

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

最後に、開発の依存関係をインストールします。

 npm i -D esbuild eslint prettier

初期設定では、 package.json内のいくつかの重要なポイントに対処する必要があります。

• main : モジュールのプライマリ エントリ ポイントを指定します。
• bin : ここでは、モジュールが提供する実行可能ファイルを指定します。
• files : これには、パッケージがパックされ、その後 npm レジストリに公開されるときに含まれるファイル パターンの配列が含まれている必要があります。
• private : パッケージはパブリックであることを目的としているため、これがfalseに設定されていることを確認してください。
• publishConfig : このアクセス権はpublicに設定する必要があります。

これらの構成を完了すると、 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": "[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

さらに、2 つの無視ファイルを追加しましょう。

 .idea node_modules dist

.gitignore

そしてnpmの場合:

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

.npmignore

最後に、ESLint のセットアップの概要を説明します。ただし、構成はパッケージの特定の要件に基づいて異なる場合があることに注意してください。

 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 構成

次に、GitHub に移動し、新しいリポジトリを確立します。パッケージにちなんで名前を付けます。

後続のコマンドを実行して続行します。

 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

パッケージソース

次に、基本的なアプリケーションを作成し、構築用に設定しましょう。 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}`); }

パッケージ例の簡単なスクリプト

概念は簡単ですmy_package_name hiを実行すると、「Hello [username]」が表示されるはずです。

この機能を検証するには、以下を使用してリポジトリからコマンドを直接実行します。

 node src/index.js hi

出力が期待どおりであれば、ソースをビルドします。

 npm run build

このコマンドが正常に実行されると、縮小されたindex.jsファイルを含むdistフォルダーが生成されます。

トークン

バージョン バンプを決定し、コミット メッセージに基づいてリリース プロセスを処理するセマンティック リリースを実行するには、正しく動作するために環境変数 ( GITHUB_TOKEN 、 NPM_TOKEN ) が必要です。トークンは GitHub シークレットから取得されるため、機密性が確保されます。

GITHUB_TOKEN設定するには、ここに移動します: https://github.com/settings/tokens

ドロップダウンを使用してトークンを生成します。新しい個人アクセス トークン (クラシック) をクリックし、図のように権限を設定します。

以下に示すようにパッケージ名を使用します。

生成したら、トークン値をコピーして機密として保管してください。これを他の人と共有しないことが重要です。このトークンはセマンティック リリース CLI ですぐに必要になるため、一時的に安全に保管してください。

NPM_TOKENを生成するには、まず次のアカウントが必要です。 npmの公式ウェブサイト。まだ登録していない場合は、登録手続きを行ってください。その後、次の場所に移動します。

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

そして、「公開」オプションを使用して「クラシック」トークンを生成します。

生成されたトークンの値をコピーし、GitHub シークレットに移動します。

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

そして、新しいシークレットをNPM_TOKENとしてリポジトリ シークレットに追加します。

シークレットが設定されたので、GitHub アクションを構成できます。

GitHub アクションのセットアップ

プロセスを自動化するには、GitHub Actions を使用します。これは、GitHub 内に統合されたCI/CDツールです。これにより、開発者はアプリケーションの構築、テスト、デプロイなどのワークフローを GitHub リポジトリから直接自動化できます。 YAML ファイルでワークフローを定義することにより、ユーザーはプッシュおよびプル リクエストやスケジュールされた時間などの特定のイベントに基づいてアクションをトリガーできるため、ソフトウェア開発プロセスがより効率的かつ自動化されます。

まず、プロジェクトのルートに.githubディレクトリを作成します。このディレクトリ内に、 workflowsサブフォルダーを作成します。

ここで、 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 }}

このワークフローは、メイン ブランチへのプッシュ イベントをトリガーします。 GitHub が提供する最新の Ubuntu 仮想マシン上でジョブを実行するように構成されています。すべての仕事を詳しく掘り下げる必要はありませんが、いくつかの特定の仕事に焦点を当ててみましょう。最後の方では、指定されたトークンを使用してnpm run semantic-releaseを呼び出す方法に注目してください。

セマンティックリリース

自動リリース プロセスには、セマンティック リリースを使用します。このツールは、コミット メッセージのセマンティクスに基づいてバージョン管理とパッケージの公開を処理します。セマンティック バージョニング (SemVer) の規則に従って、バージョン バンプ (メジャー、マイナー、またはパッチ) を決定します。コミット メッセージを分析することで、手動によるバージョン管理の手順が不要になり、バージョン番号の一貫性が保証され、リリース プロセスが合理化されます。設定してみましょう。

そのセットアップには、次を使用しますこの GitHub コードそしてそれをリポジトリ上で実行します。

 npx semantic-release-cli setup

そして、次の質問に従ってください。

 % 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

個人トークンはすでに持っているはずです。プロンプトが表示されたらそれを入力するだけです。同様に、設定した GitHub アクションは、リポジトリ シークレットで以前に確立したNPM_TOKENを利用します。ここでpackage.jsonを確認すると、バージョンは次のように表示されます。

 "version": "0.0.0-development",

そして新しいスクリプト:

 "semantic-release": "semantic-release"

これはセマンティック リリース CLI によって自動生成されました。このスクリプトを次のように拡張する必要があります。

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

これは、リリースがメイン ブランチからのみ行われることを示します。

さらに、セマンティック リリースは、 package.json内のrepositoryフィールドに基づいて説明を生成します。このフィールドには、パッケージのソース コードの場所に関する詳細が表示されます。

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

次に、すべての変更を次のようにプッシュしてみましょう。

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

コミット形式

セマンティック リリースは、構造化されたコミット メッセージの規則に基づいて、バージョン バンプの種類 (メジャー、マイナー、またはパッチ) を判断し、変更ログを生成します。このコミット規則は、「従来のコミット」形式と呼ばれることがよくあります。

この構成には、いくつかのプラグインが必要です。 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" } ] ] }

パッケージ.json

セットアップコミットフォーマットツールには、次を使用します。コミット者。インストールするには、次のコマンドに従います。

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

このコマンドには数分かかります。次に、新しいスクリプトでpackage.jsonを更新します。

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

そのスクリプトを利用するときが来ました。まずgit add .次に、 npm run commitを実行し、コミットに必要な詳細を指定します。

これは次のようになります。

 ? 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

その後、 git pushを実行します。

GitHub アクションでは、自動コミット メッセージ プロセス用の残りのパッケージがまだインストールされていないため、コミットが失敗したことがわかります。

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

ほとんどの参考資料で見落とされがちな重要な手順は、ワークフローの権限を設定することです。 https://github.com/<your_user_name>/tokky/settings/actionsに移動し、GitHub アクションに読み取りと書き込みの両方を許可する権限を構成します。

次に、少し状況を変えてみましょう。特定のキーワードfeat:に続けてメッセージを指定してコミットします。

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

package.json内のreleaseRulesを覚えていますか?これらのルールは、パッケージ リリースのバージョンを増やす方法を決定します。これを配置すると、 feat 、 fix 、 refactorなどの特定のキーワードを使用してプル リクエストを作成できます。このプル リクエストが承認され、その後メイン ブランチにマージされると、トリガーが開始されます。このトリガーは GitHub アクションをアクティブ化し、リリース プロセスを自動化し、パッケージがシームレスに更新されるようにします。

公開されたパッケージ

パッケージは正常に公開され、効率化のためにプロセス全体が自動化されました。公開を確認するには、npm 設定https://www.npmjs.com/settings/<your_user_name>/packagesに移動し、パッケージ セクションを確認します。そこに、新しく公開されたパッケージが見つかります。

npx your_package_name hiのような簡単なコマンドを使用すると、開発テストの結果をすぐに確認できます。さらに、コマンドnpm i -g your_package_nameを使用してパッケージをグローバルにインストールできます。

結論

この記事全体を通して見てきたように、初期セットアップには課題が山積する可能性がありますが、その恩恵は、合理化された一貫したリリース プロセスを確立することにあります。 GitHub Actions を活用すると、これらの複雑さが簡素化され、開発者は論理的な複雑さではなくコードの品質に集中できるようになります。

パブリック パッケージを使い始めたばかりの場合でも、公開作業で挫折に遭遇した場合でも、構造化された自動化されたワークフローを採用することには否定できない価値があります。セマンティック リリースを統合することで、一貫したバージョン管理を確保し、ソフトウェア開発への将来を見据えたアプローチを推進できます。

これにより、シームレスな公開が可能になり、頭の痛い問題が減り、デジタル世界を前進させるコードを完成させるためにより多くの時間を費やすことができます。

NPM_TOKENとGITHUB_TOKENの両方に、GitHub Actions 内で適切な権限が付与されていることが重要であることに注意してください。さらに、 package.jsonは、 publishConfigアクセスの設定で正しく構成され、 private構成がfalseに設定されていることを確認する必要があります。何か問題が発生したり、洞察がある場合は、遠慮なくコメントしてください。

参考文献

リポジトリ: https://github.com/antonkalik/tokky
セマンティック リリース CLI: https://github.com/semantic-release/cli
コミティズン: https://github.com/commitizen/cz-cli