関数のバージョン管理

このドキュメントでは、関数に使用されるバージョン管理システムについて説明します。関数のリリースバージョンは公開者が選択し、作成後は変更できません。関数の利用者に安定した信頼性の高い利用環境を提供するには、適切なバージョンを適用することが重要です。

下位互換性のある変更と破壊的変更

関数のバージョン管理システムでは、下位互換性のある変更と破壊的変更を区別します。下位互換性のある変更とは、関数の既存の利用者に支障をきたさない変更です。下位互換性のない変更は、下位互換性のない変更または破壊的変更と呼ばれます。

下位互換性のある変更の例は次のとおりです。

• 関数のシグネチャに任意の入力を追加する。
• 関数の期待される動作を変えずにパフォーマンスを最適化する。
• 関数の期待される動作を変えずにバグを修正する。

破壊的変更の例は次のとおりです。

• 関数のシグネチャに必須の入力を追加する。
• 関数のシグネチャの出力タイプを Integer から文字列に変更する。
• 関数を削除する。

既存のバージョンに対する変更に下位互換性があるかどうかを検討する際は、その変更が既存バージョンの利用者に支障をきたすか、または利用者による明示的な対応が必要になるかを考えてください。

関数に期待される利用方法を最終的に決めるのは、関数の公開者であることを忘れないでください。

セマンティックバージョニングシステム

関数のバージョンは、セマンティックバージョニング ↗システムに従って管理されます。

セマンティックバージョニングでは、バージョンは X.Y.Z の形式を取ります。X はメジャーバージョン、Y はマイナーバージョン、Z はパッチバージョンと呼ばれ、いずれも非負の整数です（例：1.2.3）。また、パッチバージョンの直後にハイフンを付け、英数字で構成されるプレリリース識別子を追加することもできます（例：1.2.3-rc1）。

このページでは、セマンティックバージョニングの概要を簡単に説明します。他のアプリケーションで確実に利用できる関数を公開するには、仕様を遵守することが重要なため、仕様の全文 ↗を読むことを推奨します。

リリースバージョンを選択する

関数の新しいバージョンを公開する際は、セマンティックバージョニング仕様の次の点を考慮してください。

• メジャーバージョン 0（0.y.z）は初期開発用です。初期開発中は関数がいつでも変更される可能性があり、利用者は関数を安定しているとみなすべきではありません。
• 下位互換性のない変更を行う場合は、メジャーバージョンを上げる必要があります。
• 下位互換性を維持しながら機能を追加する場合は、マイナーバージョンを上げる必要があります。
• 下位互換性のあるバグ修正を行う場合は、パッチバージョンを上げる必要があります。
• プレリリースバージョンは、そのバージョンが不安定であり、対応する通常のバージョンが示す互換性要件を満たさない可能性があることを示します。

下位互換性チェック

新しいバージョンを公開する前に、関数の下位互換性チェックが実行されます。具体的には、次の破壊的変更のいずれかがあると警告が表示されます。

• 関数の削除。これには、Python または TypeScript の関数コードリポジトリ内で関数を削除することも含まれます。
• 関数のシグネチャから入力を削除すること（任意の入力も含みます）。
• 関数のシグネチャ内の入力を並べ替えること。
• 関数のシグネチャに必須の入力を追加すること。
• 不適切な入力データ型の変更（Integer から文字列への変更など）。数値入力のデータ型を拡張する場合（Integer から Float への変更など）も、警告が表示されます。
• 不適切な出力データ型の変更（文字列から任意の文字列への変更など）。

何らかの理由でこれらのチェックに失敗した場合は、メジャーバージョンとしてリリースすることを推奨します。ただし、まだ初期開発段階にある場合（つまり、メジャーバージョンがまだ 0 の場合）は、この限りではありません。

留意事項：カスタム型

関数の内部データ型表現には、現在、カスタム型のフィールドの任意性に関する情報が十分に含まれていません。そのため、カスタム型の入力と出力では、任意のフィールド（TypeScript の quantity?: Integer や Python の quantity: Integer = 0 など）も含め、どのフィールドを削除または追加しても、下位互換性チェックで警告が表示される場合があります。

現在、出力のカスタム型から任意のフィールドを削除した場合や、入力のカスタム型に任意のフィールドを追加した場合に、今後は警告が表示されないように変更を進めています。

安定バージョンタグを制限する

下流の本番アプリケーションがバージョン範囲（例：>=1.2.3 <2.0.0）で関数を参照するように設定されている場合、セマンティックバージョニングの安定リリース（プレリリースではないバージョン）は、それらのアプリケーションですぐに利用される可能性があります。そのため、新しい安定バージョンとしてリリースする前に、コードの変更をレビューし、テストすることが重要です。

保護されたブランチのリポジトリ設定でトグルを有効にすることで、関数の安定バージョンのリリースに制限を適用できます。

よくある質問

0.y.z の初期開発段階でリリースバージョンを選択する

一般的には、破壊的変更はマイナーリリースで行い、下位互換性のある変更はパッチリリースで行います。これは、Node/NPM エコシステムなど、多くの開発分野で利用者が前提としている慣行であり、キャレット範囲 ↗が広く使われていることにも表れています。

下位互換性のない変更を誤ってパッチバージョンまたはマイナーバージョンとしてリリースした場合

破壊的変更をリリースしたことに気づいたら、すぐに問題を修正し、新しいマイナーバージョンで下位互換性を回復する必要があります。

次の例を考えてみます。

1. バージョン 1.0.0 の myFunction という関数があり、文字列の入力を1個受け取ります。
2. myFunction に新しい必須の入力を追加し、この変更を誤ってマイナーバージョン 1.1.0 としてリリースします。

これを修正するには、シグネチャに対する破壊的変更を元に戻し（つまり、1.1.0 で追加した新しい必須の入力を削除し）、この変更をバージョン 1.2.0 としてリリースします。

リリースに失敗した場合やまだ公開されていない場合に下位互換性をチェックする

TypeScript または Python の関数の場合、公開に失敗したり、公開に数分かかったりすることがあります。どちらの場合も、組み込みの下位互換性チェックは実行できません。新しいリリースを行う前にこれらのチェック結果を確認したい場合は、次の方法があります。

• 前回のリリースに失敗した場合は、「カスタムタグ」オプションを使用して、最後に成功したタグと比較する必要があります。
• 前回のリリースがまだ公開されていない場合は、完了するまで待つ必要があります。