はじめに
こんにちは、エンジニアの@ringoh72です。
弊社のブロックチェーンチームでは、ブロックチェーン用のアプリケーションを簡単に扱えるようにするQuragé Linkというサービスを開発しています。
フロント向けライブラリである@uniqys/qurage-link-libをnpmで公開しており、バージョニングにセマンティックバージョニングを採用しました。
開発を進める上でバージョンの付け方に疑問があったのですが、公式ドキュメントやリポジトリのissueを参照して無事解消したため、当時の背景とともに解説していきます。
TL; DR
- 特定の規格を扱う場合、1.0.0のリリースは機能の完成だけでなく規格にちゃんと則ってから行う
- リファクタはセマンティックバージョニングの対象外で、メジャーバージョンを上げる破壊的変更とはみなされない
1.0.0はどう定義すべきか
最初のリリースバージョンどうする？
僕は完成直後のQuragé Linkを引き継ぎ、npmへリリースするのが最初のタスクでした。
当時ぼんやりと2つの選択肢を考えていました。
- 機能は完成しているのでひとまず 1.0.0 でリリース
- まだまだ安心できない、 0.1.0 でリリース
「やっぱバーンとやりたい」
これが悲劇を巻き起こすことになりますが、当時は知るよしもありませんでした。
1.0.0ってなんだっけ？
1.0.0のリリース時には知らなかったことなのですが、標準規格に沿っていないインターフェースがありました。 最終的にちゃんと対応したのは3.0.0です。
セマンティックバージョニングには、FAQに「1.0.0のリリースはいつすべきでしょうか？」という項目があります。
もし既にプロダクション用途であなたのソフトウェアが利用されているのなら、それは1.0.0であるべきでしょう。またもし安定したAPIを持ち、それに依存しているユーザーが複数いるのなら、それは1.0.0であるべきでしょう。もし後方互換性について多大な心配をしているのなら、それは1.0.0であるべきでしょう。
今回は一番最後の「後方互換性についての多大な心配」について考えます。
最初のリリースをした当時は、機能が完成していたので後方互換性について多大な心配がありました。
しかし、当時「インターフェースが規格に沿っていない」と知っていたら、僕は1.0.0にしたでしょうか？ 答えはノーです。 規格に沿うまではいかなる破壊的変更も許容すべきであり、後方互換性について考えなくてもよいと思うためです。 知っていたのであれば0.1.0あたりでリリースして、規格に沿った時点でのリリースを1.0.0としていたように思います。
リファクタリングをしたらパブリックバージョンを上げるべきなのか
内向けリリースノートの作成
だいたい3,4回目くらいのリリースを迎えた頃、内部的な変更や日本語でのリリースノートを書き残すために内部向けリリースノートを作成しました。
publishの際に書くリリースノートは外向けです。 先述したリファクタリングがあった際など、内部的には大きな変更でも外部から見たら小さいことは十分考えられます。 そういった場合に「まあマイナーバージョンだから大丈夫でしょ」と安心できるのは利用者であって、開発者はそうとは限りません。 というかパッチバージョンでも安心できません。
そこで、安心するために「ここのバージョンまでは破壊的変更がなかった」ことを記録する必要性を感じていました。
内部の破壊的変更とsemver
その後何度目かのアップデートで、バージョンを決める際に1つの疑問が出てきました。
リファクタリング(内部の破壊的変更)はメジャーバージョンを上げる理由になるのか？
です。 結論から言うとこれはノーですが、結局他の破壊的変更があったためメジャーバージョンを上げることになりました。 悩んだ意味そんなになかった…
こちらのissue によると、どうやら以下のような方針のようです。 1. セマンティックバージョニングはパブリックAPIについてのもので、そもそも対象ではない 1. パブリックAPIに変化(バグや新規機能、後方互換性の破壊)がない場合リリースすべきでない
まとめ
セマンティックバージョニングの運用にあたり
- 1.0.0の基準とは何か？
- リファクタによる内部の破壊的変更はメジャーバージョンを上げなければならないのか？
という疑問を抱えていましたが、
- 特定の規格を扱う場合、1.0.0のリリースは機能の完成だけでなく規格にちゃんと則ってから行う
- リファクタはセマンティックバージョニングの対象外で、メジャーバージョンを上げる破壊的変更とはみなされない
ということがわかりました。 採用することが決まった時点で一通り公式ドキュメントに目を通していたのですが、1度読んだだけで完璧に運用することは流石に難しかったです。 とはいえよくある疑問は既に解消されていることが多く、今回も公式ドキュメントおよびissueを探すだけで済みました。
この記事が、セマンティックバージョニングを運用する一助となれれば幸いです。
