一般的なワークフローステップ

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

  • 1. モジュールを開始し、そのソースを整理して、開発者が使いやすく、あなたがメンテナンスしやすくします。
    モジュールの開発が初めての場合は、チュートリアル: Goモジュールの作成を確認してください。
    Goの分散モジュール公開システムでは、コードの整理方法が重要です。詳細については、モジュールソースの管理を参照してください。
  • 2. ローカルクライアントコードを書く準備をして、未公開のモジュール内の関数を呼び出します。
    モジュールを公開する前は、go getのようなコマンドを使用して、通常の依存関係管理ワークフローでモジュールを利用することはできません。この段階でモジュールコードをテストする良い方法は、呼び出しコードのローカルディレクトリ内で試すことです。
    ローカル開発については、未公開モジュールに対するコーディングを参照してください。
  • 3. モジュールのコードが他の開発者に試してもらう準備ができたら、v0のプレリリースを開始します。アルファ版やベータ版などです。詳細については、プレリリースバージョンの公開を参照してください。
  • 4. v0をリリースしますが、安定性は保証されていませんが、ユーザーが試すことができます。詳細については、最初の（不安定な）バージョンの公開を参照してください。
  • 5. v0バージョンが公開された後は、新しいバージョンをリリースし続けることができます（そして、すべきです！）。
    これらの新しいバージョンには、バグ修正（パッチリリース）、モジュールの公開APIへの追加（マイナーバージョン）、さらには破壊的変更が含まれる場合があります。v0リリースは安定性や後方互換性を保証しないため、そのバージョンで破壊的変更を行うことができます。
    詳細については、バグ修正の公開および非破壊的API変更の公開を参照してください。
  • 6. 安定したバージョンのリリース準備が整ったら、アルファ版やベータ版としてプレリリースを公開します。詳細については、プレリリースバージョンの公開を参照してください。
  • 7. 最初の安定リリースとしてv1をリリースします。
    これは、モジュールの安定性に関するコミットメントを行う最初のリリースです。詳細については、最初の安定バージョンの公開を参照してください。
  • 8. v1バージョンでは、バグを修正し続け、必要に応じてモジュールの公開APIに追加を行います。
    詳細については、バグ修正の公開および非破壊的API変更の公開を参照してください。
  • 9. 避けられない場合は、新しいメジャーバージョンで破壊的変更を公開します。
    メジャーバージョンの更新（例: v1.x.xからv2.x.xへの更新）は、モジュールのユーザーにとって非常に破壊的なアップグレードとなる可能性があります。これは最後の手段とすべきです。詳細については、破壊的API変更の公開を参照してください。

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

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

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

プレリリースバージョンの公開

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

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

以下は2つの例です: 

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

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

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

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

最初の（不安定な）バージョンの公開

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

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

他の公開バージョンと同様に、安定したv1バージョンをリリースするための変更を行う際に、v0バージョン番号のマイナー部分とパッチ部分をインクリメントできます。たとえば、v0.0.0をリリースした後、最初のバグ修正セットを含むv0.0.1をリリースすることがあります。

以下はバージョン番号の例です: 

  1. v0.1.3

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

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

最初の安定リリースはv1.x.xのバージョン番号を持ちます。最初の安定リリースは、フィードバックを得てバグを修正し、ユーザーのためにモジュールを安定化させたプレリリースおよびv0リリースに続くものです。

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

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

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

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

以下は安定バージョン番号の例です: 

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