モジュールのリリースとバージョン管理のワークフロー

他の開発者が使用するモジュールを開発する際には、モジュールを使用する開発者にとって信頼性が高く一貫したエクスペリエンスを確保するためのワークフローに従うことができます。このトピックでは、そのワークフローの主要な手順について説明します。

モジュールの開発の概要については、「モジュールの開発と公開」を参照してください。

こちらも参照

コードで外部パッケージを使用したいだけであれば、「依存関係の管理」を必ず参照してください。
新しいバージョンごとに、そのバージョン番号でモジュールへの変更を通知します。詳細については、「モジュールのバージョン番号付け」を参照してください。

一般的なワークフローの手順

次のシーケンスは、新しいモジュールのリリースとバージョン管理のワークフローの手順を示しています。各手順の詳細については、このトピックのセクションを参照してください。

モジュールを開始し、開発者が使いやすく、あなたが保守しやすいようにソースを整理します。

モジュールの開発が初めての場合は、「チュートリアル: Go モジュールを作成する」を参照してください。

Go の分散型モジュール公開システムでは、コードの整理方法が重要です。詳細については、「モジュールのソースの管理」を参照してください。
未公開のモジュール内の関数を呼び出すローカルクライアントコードを作成するように設定します。

モジュールを公開するまで、go get などのコマンドを使用した一般的な依存関係管理ワークフローでは使用できません。この段階でモジュールコードをテストする良い方法は、呼び出し元コードのローカルディレクトリにある状態で試すことです。

ローカル開発の詳細については、「未公開のモジュールに対するコーディング」を参照してください。
モジュールのコードが他の開発者によって試される準備ができたら、アルファ版やベータ版などのv0 プレリリース版の公開を開始します。詳細については、「プレリリース版の公開」を参照してください。
安定性は保証されていませんが、ユーザーが試すことができるv0 をリリースします。詳細については、「最初の (不安定な) バージョンの公開」を参照してください。
v0 バージョンが公開されたら、引き続き新しいバージョンをリリースできます (また、そうすべきです!)。

これらの新しいバージョンには、バグ修正 (パッチリリース)、モジュールのパブリック API への追加 (マイナーリリース)、さらには破壊的変更が含まれる場合があります。v0 リリースは安定性や後方互換性を保証しないため、そのバージョンで破壊的変更を行うことができます。

詳細については、「バグ修正の公開」と「破壊的でない API 変更の公開」を参照してください。
安定版のリリース準備ができたら、プレリリース版をアルファ版およびベータ版として公開します。詳細については、「プレリリース版の公開」を参照してください。
最初の安定版リリースとして v1 をリリースします。

これは、モジュールの安定性についてコミットメントを行う最初のリリースです。詳細については、「最初の安定版バージョンの公開」を参照してください。
v1 バージョンでは、引き続きバグを修正し、必要に応じてモジュールのパブリック API に追加を行います。

詳細については、「バグ修正の公開」と「破壊的でない API 変更の公開」を参照してください。
避けられない場合は、新しいメジャーバージョンで破壊的変更を公開します。

v1.x.x から v2.x.x へのメジャーバージョンアップグレードは、モジュールのユーザーにとって非常に混乱を招くアップグレードとなる可能性があります。これは最終手段であるべきです。詳細については、「破壊的 API 変更の公開」を参照してください。

未公開のモジュールに対するコーディング

モジュールまたはモジュールの新しいバージョンの開発を開始するとき、まだ公開していません。モジュールを公開するまで、Go コマンドを使用してモジュールを依存関係として追加することはできません。代わりに、最初は、未公開のモジュール内の関数を呼び出す別のモジュールでクライアントコードを作成するときに、ローカルファイルシステム上のモジュールのコピーを参照する必要があります。

クライアントモジュールの go.mod ファイルで replace ディレクティブを使用することにより、クライアントモジュールの go.mod ファイルからローカルでモジュールを参照できます。詳細については、「ローカルディレクトリ内のモジュールコードの要求」を参照してください。

プレリリース版の公開

プレリリース版を公開して、他の人がモジュールを試してフィードバックを提供できるようにすることができます。プレリリース版は安定性を保証しません。

プレリリース版のバージョン番号には、プレリリース識別子が追加されます。バージョン番号の詳細については、「モジュールのバージョン番号付け」を参照してください。

以下に2つの例を示します

v0.2.1-beta.1
v1.2.3-alpha

プレリリース版を公開するときは、プレリリース版を使用する開発者は go get コマンドでバージョンを明示的に指定する必要があることを覚えておいてください。これは、デフォルトで go コマンドが、要求しているモジュールを見つけるときに、プレリリース版よりもリリース版を優先するためです。したがって、開発者は次の例のように明示的に指定してプレリリース版を取得する必要があります

go get example.com/theirmodule@v1.2.3-alpha

リポジトリ内のモジュールコードにタグを付け、タグにプレリリース識別子を指定することでプレリリース版を公開します。詳細については、「モジュールの公開」を参照してください。

最初の (不安定な) バージョンの公開

プレリリース版を公開する場合と同様に、安定性や後方互換性を保証しないリリース版を公開できますが、ユーザーにモジュールを試してフィードバックを提供してもらう機会を与えます。

不安定なリリースとは、バージョン番号が v0.x.x の範囲にあるものです。v0 バージョンは安定性や後方互換性を保証しません。しかし、v1 以降で安定性のコミットメントを行う前に、フィードバックを得て API を改良する方法を提供します。詳細については、「モジュールのバージョン番号付け」を参照してください。

他の公開済みバージョンと同様に、安定版の v1 バージョンのリリースに向けて変更を加える際に、v0 バージョン番号のマイナーおよびパッチ部分をインクリメントできます。たとえば、v.0.0.0 をリリースした後、最初のバグ修正セットを含む v0.0.1 をリリースする場合があります。

バージョン番号の例を次に示します

v0.1.3

リポジトリ内のモジュールコードにタグを付け、タグに v0 バージョン番号を指定することで不安定なリリースを公開します。詳細については、「モジュールの公開」を参照してください。

最初の安定版バージョンの公開

最初の安定版リリースには、v1.x.x のバージョン番号が付けられます。最初の安定版リリースは、フィードバックを得て、バグを修正し、ユーザーのためにモジュールを安定させたプレリリース版および v0 リリースの後に続きます。

v1 リリースでは、モジュールを使用する開発者に対して以下のコミットメントを行います

彼らは、自分のコードを壊すことなく、メジャーバージョンのその後のマイナーリリースおよびパッチリリースにアップグレードできます。
後方互換性を壊すような、モジュールのパブリック API (関数とメソッドのシグネチャを含む) へのさらなる変更は行いません。
後方互換性を壊すようなエクスポートされた型を削除することはありません。
API への将来の変更 (構造体に新しいフィールドを追加するなど) は、後方互換性があり、新しいマイナーリリースに含まれます。
バグ修正 (セキュリティ修正など) は、パッチリリースまたはマイナーリリースの一部として含まれます。

注: 最初のメジャーバージョンが v0 リリースである場合でも、v0 バージョンは安定性や後方互換性を保証しません。結果として、v0 から v1 にインクリメントするとき、v0 リリースは安定していると見なされなかったため、後方互換性を壊すことを気にする必要はありません。

バージョン番号の詳細については、「モジュールのバージョン番号付け」を参照してください。

安定版のバージョン番号の例を次に示します

v1.0.0

リポジトリ内のモジュールコードにタグを付け、タグに v1 バージョン番号を指定することで最初の安定版リリースを公開します。詳細については、「モジュールの公開」を参照してください。

バグ修正の公開

変更がバグ修正に限定されたリリースを公開できます。これはパッチリリースとして知られています。

パッチリリースには、軽微な変更のみが含まれます。特に、モジュールのパブリック API への変更は含まれません。利用コードの開発者は、安全に、そしてコードを変更する必要なく、このバージョンにアップグレードできます。

注: パッチリリースでは、モジュール自体の推移的依存関係をパッチリリース以上にアップグレードしないようにしてください。そうしないと、モジュールのパッチにアップグレードする人が、意図せずに使用している推移的依存関係に、より侵襲的な変更が引き込まれてしまう可能性があります。

パッチリリースでは、モジュールのバージョン番号のパッチ部分がインクリメントされます。詳細については、「モジュールのバージョン番号付け」を参照してください。

以下の例では、v1.0.1 がパッチリリースです。

古いバージョン: v1.0.0

新しいバージョン: v1.0.1

リポジトリ内のモジュールコードにタグを付け、タグ内のパッチバージョン番号をインクリメントすることでパッチリリースを公開します。詳細については、「モジュールの公開」を参照してください。

非破壊的 API 変更の公開

モジュールのパブリック API に非破壊的変更を加え、それらの変更をマイナーバージョンリリースで公開できます。

このバージョンは API を変更しますが、呼び出し元コードを壊すような方法ではありません。これには、モジュール自身の依存関係の変更、または新しい関数、メソッド、構造体フィールド、または型の追加が含まれる場合があります。これに含まれる変更があったとしても、この種のリリースは、モジュールの関数を呼び出す既存のコードに対して後方互換性と安定性を保証します。

マイナーリリースでは、モジュールのバージョン番号のマイナー部分がインクリメントされます。詳細については、「モジュールのバージョン番号付け」を参照してください。

以下の例では、v1.1.0 がマイナーリリースです。

古いバージョン: v1.0.1

新しいバージョン: v1.1.0

リポジトリ内のモジュールコードにタグを付け、タグ内のマイナーバージョン番号をインクリメントすることでマイナーリリースを公開します。詳細については、「モジュールの公開」を参照してください。

破壊的 API 変更の公開

メジャーバージョンリリースを公開することで、後方互換性を壊すバージョンを公開できます。

メジャーバージョンリリースは後方互換性を保証しません。これは通常、モジュールの以前のバージョンを使用するコードを壊すような、モジュールのパブリック API への変更が含まれるためです。

メジャーバージョンアップグレードがモジュールに依存するコードに与える破壊的な影響を考慮すると、可能であればメジャーバージョンアップグレードは避けるべきです。メジャーバージョンアップグレードの詳細については、「メジャーバージョンアップグレードの開発」を参照してください。破壊的変更を避けるための戦略については、ブログ記事「モジュールの互換性を維持する」を参照してください。

他の種類のバージョンを公開するには、基本的にバージョン番号でモジュールコードにタグを付ける必要がありますが、メジャーバージョンアップグレードを公開するには、より多くの手順が必要です。

新しいメジャーバージョンの開発を開始する前に、リポジトリに新しいバージョンのソースの場所を作成します。

これを行う1つの方法は、リポジトリに新しいブランチを作成することです。このブランチは、新しいメジャーバージョンとその後のマイナーおよびパッチバージョン専用です。詳細については、「モジュールのソースの管理」を参照してください。
モジュールの go.mod ファイルで、以下の例のように新しいメジャーバージョン番号を付加するようにモジュールパスを修正します
```
example.com/mymodule/v2
```
モジュールパスがモジュールの識別子であるため、この変更は実質的に新しいモジュールを作成します。また、パッケージパスも変更され、開発者が意図せずにコードを壊すバージョンをインポートしないようにします。代わりに、アップグレードしたい開発者は、古いパスを新しいパスに明示的に置き換えます。
コード内で、更新しているモジュール内のパッケージ (更新しているモジュール内のパッケージを含む) をインポートしているパッケージパスを変更します。モジュールパスを変更したため、これを行う必要があります。
新しいリリースと同様に、正式なリリースを公開する前に、フィードバックとバグレポートを得るためにプレリリース版を公開する必要があります。
リポジトリ内のモジュールコードにタグを付け、タグ内のメジャーバージョン番号をインクリメントすることで、新しいメジャーバージョンを公開します (例: v1.5.2 から v2.0.0)。

詳細については、「モジュールの公開」を参照してください。