semantic-versioning | Casual Developers Note

NPMモジュールを自動的にセマンティック・バージョニングで管理する方法(semantic-release編)

NPMモジュールを自動的にセマンティック・バージョニングで管理するためのモジュール「semantic-release」の導入方法を紹介します。

はじめに

NPMモジュールをバージョン管理する場合、セマンティック・バージョニングに従うのが一般的です。これを手動でやろうとすると、リリースの運用ルールを自分で決めて、NPMコマンドを使ってバージョンを上げてNPMに公開することになります。手動というのはミスも起きますし、そもそも面倒です。そこで、コミットメッセージのルールを決めることで、コミットするだけで自動的にセマンティック・バージョニングでバージョンを上げてNPMに公開してくれるモジュールが「semantic-release」です。今回は、「semantic-release」の導入方法を紹介します。

また、NPMモジュールを自作で作成する方法を知りたい人は以前の記事を参照してください。

セマンティック・バージョニングとは？

セマンティック・バージョニング(Semantic Versioning)とは、仕様が公開されており、ほとんどのNPMモジュールで採用されているバージョン管理の方法です。ざっくり言うと、バージョンを「X.Y.Z」とすると、「X」はMajor version(ブレイキングチェンジがある場合に上げる)、「Y」はMinor version(機能追加がある場合に上げる)、「Z」はPatch version(バグフィックスの場合に上げる)としてバージョンを定義して管理する方法です。

semantic-releaseとは？

semantic-releaseとは、コミットメッセージの内容から判断して、自動的に適切にバージョン(セマンティック・バージョニングに従う)を上げてNPMへ公開するためのモジュールです。これを導入すれば、コミットメッセージだけでNPMモジュールを管理できるようになります。コミットメッセージのルールはカスタマイズできますが、デフォルトではAngular Commit Message Conventionsに従う形になり、以下のようになります。

feat: 新しい機能の追加(Minor versionを上げる)
fix: バグフィックス(Patch versionを上げる)
docs: ドキュメントだけ変更
style: フォーマットの変更などのソースコードに影響を与えない変更
refactor: バグフィックスや機能追加を伴わないソースコードの変更
perf: パフォーマンス改善のためのソースコードの変更
test: 不足しているテストコードの追加や既存のテストコードの修正
chore: ビルドプロセスや補助的なツールやライブラリの変更

自作のNPMモジュールにsemantic-releaseを適用する

それでは、既存の自作のNPMモジュールのプロジェクトに適用してみましょう。ビルドツールはTravis CI、パッケージ管理はYarnを使うことにします。(代わりにビルドツールとしてCircle CI、パッケージ管理ツールとしてNPMを使うことももちろんできます。)

semantic-releaseをセットアップする

まずは、公式ドキュメント通りに、CLIを入れて、セットアップします。

$ yarn global add semantic-release-cli
$ cd my-npm-module
$ semantic-release-cli setup
? What is your npm registry? https://registry.npmjs.org/
? What is your npm username? you
? What is your npm password? [hidden]
? What is your GitHub username? you
? What is your GitHub password? [hidden]
? What CI are you using? Travis CI
Please refer to https://github.com/semantic-release/semantic-release/blob/master/docs/recipes/travis.md to configure your .travis.yml file.
$ cat package.json
{
...
  "version": "0.0.0-development",
...
  "repository": "https://github.com/you/my-npm-module.git",
...
  "devDependencies": {
...
    "semantic-release": "^15.13.3"
  },
...
  "scripts": {
...
    "semantic-release": "semantic-release"
  },
...
}

バージョンにはデフォルトで「0.0.0-development」と書かれますが、semantic-releaseではpackage.jsonのversionは使わず、NPM側のバージョンが使われます。

Travis CI用の設定ファイルを設定する

「.travis.yml」に以下のように設定します。テストを実行し、テストが成功してかつバージョンが上がっている場合にNPMに公開させる設定です。

language: node_js
node_js:
  - 10
  - 8

jobs:
  include:
    - stage: release
      node_js: lts/*
      deploy:
        provider: script
        skip_cleanup: true
        script:
          - yarn semantic-release

Travis CI用の設定方法は公式ドキュメントを参照してください。

commitizenを設定する

コミットメッセージのルールが決まっていても手動で入力するとミスがおきます。なので、正しくコミットメッセージを入力するために「commitizen」の「cz-cli」のモジュールを使います。ついでに、チェンジログを自動で追加してくれる「cz-conventional-changelog」のモジュールも導入します。

$ yarn add --dev commitizen
$ yarn commitizen init cz-conventional-changelog --yarn --dev --exact
$ cat package.json
{
...
  "devDependencies": {
...
    "cz-conventional-changelog": "2.1.0",
  },
...
  "config": {
    "commitizen": {
      "path": "./node_modules/cz-conventional-changelog"
    }
  }
}
$ vi package.json
{
...
  "scripts": {
    "commit": "git-cz",
...
  },
...
}

これで設定は完了です。グローバルに導入してもよいですが、全てのプロジェクトに適用することはあまりないと思うので、モジュール内に導入しています。

使い方

最後に、使ってみましょう。今回は何かバグフィックスをしたと仮定してコミットしてみます。

$ git add .
$ yarn commit
...
? Select the type of change that you're committing: (Use arrow keys)
  feat:     A new feature 
❯ fix:      A bug fix 
  docs:     Documentation only changes 
  style:    Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) 
  refactor: A code change that neither fixes a bug nor adds a feature 
  perf:     A code change that improves performance 
  test:     Adding missing tests or correcting existing tests 
(Move up and down to reveal more choices)
...
? Select the type of change that you're committing: fix:       A bug fix
? What is the scope of this change (e.g. component or file name)? (press enter to skip)
 
? Write a short, imperative tense description of the change:
 Fix any bugs
? 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

[master 043b0c2] fix: Fix any bugs
$ git push origin master

これでTravis CIでテストが成功すれば、Patch versionが上がり、NPMに公開されます。