この記事は、弁護士ドットコム Advent Calendarの17日目の記事です。

この記事で伝えたいこと

GitHub Actions とsemantic-releaseで、自動で高品質npmパッケージをリリースできます
使う人も作る人も簡単にメンテナンスできるようことが大事
textlint ルールを npm パッケージとして OSS 公開

誰でも使いやすいパッケージとは何か

使いやすいパッケージとは、大きく下記の4つがあげられます。

セマンティックバージョンで変更内容とバージョンが紐づいてわかりやすい
リリース頻度が多く機能追加、バグ修正に素早く対応している
リリースノートが正しく書かれて、変更内容が瞬時に把握できる
テストがあり、動作が担保されている。

パッケージの中身も当然大事です。ですがいくら中身が良くても一般公開時にこれらが欠けると、使いづらくなってしまいます。

変更内容を見てリリースノート作って、バージョンを決めるのは大変

セマンティックバージョンで毎回整合性が担保できていますか？何をリリースしたか確認して、必要な変更だけリリースノート書けていますか？

これらを愚直に手動で実現するのは大変です。

作業が増えるほど、リリースのハードルがあがます。デザイナーさんも簡単にリリースできるようにするなど、夢のまた夢です。

パッケージ公開までのフローを設計する

可能な限り作業を自動化する前提で考えます。手動での介入を最小限にすることで、ミスを減らし、運用コストを削減できます。

npmパッケージリリース支援ライブラリ

よく使われるふたつのライブラリがあります。今回は自動化前提なのでsemantic-releaseを採用しました。

semantic-release

CI で実行&完全に自動化することが前提のライブラリです。

新しいリリースをメンテナやユーザに通知したり、コミットメッセージを使用してコードベースの変更を文書化できます。

マージに基づいて、 Git タグうち&npm などで公開できます。

standard-version

バージョン管理、変更ログの生成、および Git タグ付けを処理してくれます。コミットメッセージの分解は同じです。

大きく違うのはローカルで動かす前提で、リモート反映はしないこと。またnpm のパッケージ公開までは対応してません。

コミットメッセージとバージョン

commit メッセージ

コミットメッセージはAngular のコミットメッセージフォーマットに従います。

これによりコミットメッセージを解析して、自動でバージョンが決まりCHANGELOG.mdが更新されます。

<種別>: <具体的な変更内容>

例
fix: 日本語の副詞「と」のルールを修正

バージョン

デフォルトのcommit時の種別とバージョンの対応は下記です。設定を変更すれば、オリジナルの種別を追加できます。

種別	内容	マージリリース	バージョン
feat	新しい機能	〇	Miner Release
fix	バグ修正&軽微な修正	〇	Patch Release
perf	コードのパフォーマンス修正	〇	Patch Release
BREAKING CHANGE	互換性のない破壊的変更	〇	Major Release
etc..

コミッター全員がコミットメッセージ綺麗するのが必須？

GitHubにはマージ方法が 3 種類あります。

Create a merge commit
- フィーチャブランチからのすべてのコミットがマージコミット内でベースブランチに追加されます。
Rebase and merge
- トピックブランチ（あるいはheadブランチ）のすべてのコミットが、マージコミットなしに個別にベースブランチに追加されます。
Squash and merge
- そのプルリクエストのコミットは１つのコミットにsquashされます。

Squash and mergeを使い、マージする際にメンテナーが Squash して commit メッセージを加工するのが良いでしょう。そうすれば、全てのコミッターがコミットメッセージを完璧にする必要はないです。

万が一ルールに沿っていなくても、無視されるので影響はありません。

semantic-releaseの設定

package.jsonに使うプラグインとブランチを指定します。

今回は、commit解析によるCHAGELOG.md&リリースノートの作成、GitHubを使ったGitでのタグうちと差分のcommitまで行います。

package.json

  "release": {
    "plugins": [
      "@semantic-release/commit-analyzer",
      "@semantic-release/release-notes-generator",
      "@semantic-release/changelog",
      "@semantic-release/npm",
      "@semantic-release/github",
      "@semantic-release/git"
    ],
    "branches": [
      "main"
    ]
  }

処理のイメージは下記のようになります。

ステップ	説明
条件の確認	すべての条件を確認して、条件があっているか確認します。
最後のリリースを取得	分析して、最後のリリースに対応するコミットを取得します。
コミットの分析	前回のリリース以降に追加されたコミットに基づいて、リリースのタイプを決定します。
リリースを確認する	リリースの適合性を確認します。
メモを生成する	前回のリリース以降に追加されたコミットのリリースノートを生成します。
Gitタグを作成する	新しいリリースバージョンに対応するGitタグを作成します。
準備	リリースを準備します。
公開	リリースを公開します。
通知する	新しいリリースまたはエラーを通知します。

GitHub Action Workflowで自動化

npmのリリースのためにNPM_TOKENにnpmのアクセストークンをGitHubのレポジトリのSECRETSに設定しておきます。GitHubの操作も行いますが、自動でGITHUB_TOKENという名前のGitHubアクセストークンが設定されているので対応不要です。

GitHub Actions のワークフローは、Test と Release のふたつを想定します。

こちらは、Release用のワークフローです。起動条件にTestの成功を指定し、テストが通った時だけ起動します。

name: Release
on:
  workflow_run:
    workflows:
      - Test
    branches:
      - main
    types:
      - completed

jobs:
  release:
    name: Release
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'success' }}

    steps:
      - name: Checkout
        uses: actions/checkout@v2
        with:
          fetch-depth: 0

      - name: Setup NodeJS 14
        uses: actions/setup-node@v2
        with:
          node-version: 14

      - name: Install dependencies
        run: npm ci

      - name: Release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npx semantic-release

リリースの流れ

プルリクエストのマージからまとめるとこうなります。

プルリクエストをマージ
Test ワークフロー
1. テスト実行
Release ワークフロー
1. Test が無事に終わっていたらトリガー
2. Git タグを解析して、最後のリリースに該当するコミットを取得
3. 前回のリリース以降に追加されたコミットをもとに、リリースの種類を決定
4. リリースの適合性を確認
5. 前回のリリース以降に追加されたコミットのリリースノートを作成
6. 新しいリリースバージョンに対応する Git タグを作成
7. npm package リリース
8. 新しいリリースやエラーを通知

このフローで公開しているtextlintルールパッケージ

実際に上記のワークフローを使いtextlintのルールをnpmで公開しました。

弁コムサービス内の文字校正のレビューコストが高くなってました。ルールの数が増えると、レビューに時間がかかります。レビュアーによっても指摘内容が異なり、レビューの難易度もあがります。

そのためMarkdown などのテキストファイルを特定のルールにしたがってチェックするtextlintを導入しました。Slackをインターフェイスにして、裏側でtextlintの上記のルールを使ったAPIが動いてます。

一緒に作ったデザイナーさんの記事もあるので、ぜひ見てください。

まとめ

GitHub Actions & semantic-version での自動リリースは非常に便利なので、楽に高品質なパッケージを公開しましょう。

使う人も作る人にも優しいOSSの提供を目指します。

GitHub Actionsとsemantic-releaseで、自動で高品質npmパッケージを一般公開する