初めに

CI/CDでお馴染みの「semantic-release」

概念や使い方を理解していたつもりでも、いざ自分で設定しようとすると世の中に溢れている情報がバラバラ過ぎて自分の知りたいことを探すのが非常に手間であることに気がつきました。

そんな自分に向けて、どんなことを知りたくて、何の情報を得たのか、時系列的にまとめていきます。

そもそも理解すべき事実

世の中で言われる「semantic-release」はNodejsベースのパッケージです。初めての方がいきなり触り始めるのはオススメしません。

あくまでツールとして「リリースする作業を自動化するよ」というものなので、まずはリリース作業を手動で行なった場合、どんなことをすべきかを理解してから、触り始めることを強くオススメします。

リリースって何するもの？

みなさんご存知の github.com でリリースする作業を見てみましょう。以降の手順はあえて単純に説明してます。

1. 何でもいいからコードを書く
2. Release Branch (e.g., main, master) にCommit ^[1]する

これだけだと、一体何をリリースしたのか第三者には分かりませんし、いつの時点のコードを使えば良いのか全く意味が分かりません。そこで考え出されたのが「Semantic Version」という考え方です。

Semantic Version とは

「Semantic Version」とは一言で表すと「バージョンをつける時はみんな同じルールでつけようぜ」という考え方です。

例えば、あなたが最初にコードを書いたものを適当に「v1」とバージョン情報をつけましょう。

これに対して次のコード変更が今後考えられます。

1. 「v1」そのままで軽微なバグ修正
2. 「v1」に新しい機能を追加
3. 「v1」から大きく機能の変更

「1」について利用者は「ふーん」程度の関心しかないことでしょう。ただ「2」に関しては「XXの機能が欲しかった！！」という利用者にとっては非常にありがたい情報です。

さらに「3」については機能が大きく変わるので今まで通りに動作しない可能性だってあり得ます。

こういう状況にぴったりな情報を皆で統一して発信していこう！とした場合にルールがあると便利ですよね？

こう言った経緯から「Semantic Version」という考え方が生まれました。

Semantic Versionの例

先ほどの3つの場合に応じて以下のように数字を繰り上げていきます。

• Semantic Version: vX.Y.Z (例ではv1.0.0から始める)

1. 「v1」そのままで軽微なバグ修正: v1.0.0 -> v1.0.1
2. 「v1」に新しい機能を追加: v1.0.0 -> v1.1.0
3. 「v1」から大きく機能の変更: v1.0.0 -> v2.0.0

それぞれのドットで区切られた数字に対して1つずつ数字を足していくだけです。そして数字の位置さえ守れば、いくつ数字を足していくかはコードをリリースする人に委ねられます。本当にたくさんのバグ修正したから「v1.0.0 -> v1.0.100」とかも可能です。

あくまで数字をどのように区切るか、という考え方が「Semantic Version」です。

何をリリースしたの？

自分がどんなコードを書いたのか、それは書いた人にとっては明白です。なぜなら自分で書いたから。

けど小説でも何でも「新刊が出ました！」だけの情報だと「何が新しいの？」という疑問が湧くかと思います。そういう場合に利用されるのが「あらすじ」だったり「本の帯」だったりしますよね。

それと同じものをリリース作業にも加えてあげる必要があります。これをエンジニア業界では「Release Notes」(リリースノート)にまとめる文化があります。

Release Notesとは

先ほどの「Semantic Version: vX.Y.Z)」では位置に応じて名前がついています。

• X: Major (メジャー)
• Y: Minor (マイナー)
• Z: Patch (パッチ)

そして何のバージョンをリリースするかで利用者の関心毎は異なります。

Patch リリース

軽微なバグ修正だけであれば「何のバグを修正したか」程度で十分です。

Minor リリース

新しい機能を追加したのであれば、Patchリリースの情報に加えて「新しい機能をどのような場面で使えるか」のような使い方情報があると利用者は喜びます。

Major リリース

大きな変更があった場合は、Minorリリースまでの情報に加えて「何の機能を削除/追加したか、古いバージョンから移行する場合にはどのような手順が必要か」を書いてあげると非常に親切です。

最後に

本当は「github.com上で手動でリリースしてみた」も追加するとより理解が深まると思うのですが今回はこれまで。

本スクラップで反応があるか、気が向いた際に記事化します。