データ API ビルダーのポリシー
一連のポリシーは、破壊的変更、通知、リリース、バージョン管理に関連するデータ API ビルダーを管理します。
バージョン管理とリリース
Data API ビルダーのコンテキストでの リリース は、公開されているすべてのバージョンのソフトウェアを指し、形式で Major.Minor.Patch 識別されます。 これらのリリースは、 安定版、 破壊的変更、プレビューの 3 つのカテゴリに分類 されます。
安定版リリース
Data API ビルダーの 安定したバージョン は下位互換性があります。 下位互換性とは、Data API ビルダーの 1 つのバージョンに依存する記述コードは、正確性や既存の機能を維持するためにコードを変更することなく、新しい安定したバージョンを採用できることを意味します。
破壊的変更リリース
データ API ビルダーの 破壊的変更バージョン は下位互換性がありません。 既存のクライアント コードで破壊的変更バージョンを採用するには、コードを変更して、クライアントが以前のバージョンをターゲットにしたときとまったく同じように動作するようにする必要がある場合があります。
破壊的変更バージョンは、破壊的変更リストの記事と GitHub リリースの変更の説明で発表されます。 プレビュー/リリース候補バージョンの公開は、重大なセキュリティ、プライバシー、または法的な問題を修正しない限り、破壊的変更バージョンより前です。 以前のバージョンの Data API ビルダーは GitHub リリース ページで引き続き使用できる場合がありますが、バグ修正を含む最新リリースにアップグレードすることをお勧めします。
プレビュー リリース
データ API ビルダーのプレビュー リリースは、バージョン管理スキームで X.Y.Z-rc 識別されます。 サフィックスは -rc 、ビルドが "リリース候補" であることを示します。プレビュー リリースは、新機能やその他の変更に関するフィードバックを収集するために使用されます。
最後の安定バージョンから意図的に大幅な変更を行う予定がない限り、最新の安定したリリースと新しいプレビュー機能のすべてを含む次のプレビュー バージョンを公開します。 次の Data API ビルダーの更新プログラムでは、プレビュー バージョン間で追加した新しいプレビュー機能の一部が壊れる可能性があります。 この破壊的動作は、再び動作するようにコードを変更する必要がある場合があります。
プレビュー バージョンは、長期的または運用環境での使用を目的としていません。 新しい安定版またはプレビュー 版が利用可能になると、古いプレビュー バージョンにアクセスできなくなる可能性があります。 プレビュー バージョンは、新機能に積極的に取り組んでおり、リリース後すぐにプレビュー以外のバージョンに切り替える準備ができている場合にのみ使用することをお勧めします。 プレビュー バージョンの一部の機能が新しい安定バージョンに含まれている場合は、残りのプレビュー機能が新しいプレビュー バージョンに追加され、試すことができます。
バージョン変更テーブル
重要
重要な製品のバグ、法律、セキュリティ、またはプライバシーに関する懸念に対処する場合、マイナー リリースまたはパッチ リリースに破壊的変更が導入される場合があります。
| リリースの種類 | アップグレード前のバージョン | 新しいバージョン | メモ |
|---|---|---|---|
| 互換性に影響する変更点 | 1.Y.Z |
2.Y.Z |
新機能とバグ修正と、重大な変更。 |
| Stable | 1.1.Z |
1.2.Z |
重要な製品のバグ、法的、セキュリティ、またはプライバシーに関する懸念に対処しない限り、破壊的変更のない新機能とバグ修正。 |
| Stable | 1.1.1 |
1.1.2 |
重要な製品のバグ、法的、セキュリティ、プライバシーに関する懸念に対処しない限り、新機能のないバグ修正や破壊的変更。 |
| プレビュー | X.Y.1-rc |
X.Y.2-rc |
新しいプレビュー機能とバグ修正。 (メジャー バージョンがバンプされた場合は、破壊的変更が含まれます)。 |
重大な変更
セキュリティに優先順位を付け、機能を強化し、コードの品質を維持するために、新しいバージョンのソフトウェアには破壊的変更が含まれる場合があります。 これらの変更は、慎重なアーキテクチャの選択を通じて最小限に抑えるように努めていますが、引き続き発生する可能性があります。 このような場合は、それらを発表し、可能な解決策を提供することを優先します。
重要
変更が重大でないと見なされる場合、または重大な製品のバグや法的、セキュリティ、またはプライバシーに関する懸念に対処するために重大な変更が行われている場合は、事前の通知なしに変更を行う場合があります。
破壊的変更とは
破壊的変更とは、中断を防ぐためにアプリケーションを更新する必要がある変更です。 データ API ビルダーでは、破壊的変更には、REST API コントラクトの変更、スキーマの生成GraphQL、互換性と機能に影響を与えるその他の要素が含まれる場合があります。
破壊的変更の例
次の例は、Data API ビルダーに対する破壊的変更の 無尽 蔵の一覧です。
- REST API コントラクトの変更
- スキーマ生成における変更GraphQL
- 下位互換性に影響を与える変更
- API またはパラメーターの削除または名前変更
- エラー コードの変更
- アクセス許可定義機能の調整
- 許可されたパラメーター、要求フィールド、または応答フィールドの削除
- 既定値のない必須パラメーターまたは要求フィールドの追加
- 目的の API エンドポイント機能の変更
非破壊的変更の定義
破壊的でない変更とは、中断を引き起こさずにアプリケーションに統合できる変更を指します。 通常、非破壊的変更は実装後に伝達されます。 アプリケーションは、事前の通知なしにこれらの変更を処理するように設計する必要があります。
破壊的変更以外の例
次の例は、Data API ビルダーに対する破壊的でない変更の 無 尽蔵の一覧です。
- 新しいエンドポイントの概要
- 既存のエンドポイントへのメソッドの追加
- 回答・要望に新たなフィールドを組み込む
- 応答内のフィールド順序の調整
- 省略可能な要求ヘッダーの概要
- データ長と応答サイズの変更
- エラー メッセージとコードの変更
- HTTP 応答コードの修正
- 生成された OpenAPI ドキュメント内の追加のメタデータ
破壊的変更を伝える方法
重大な変更について迅速にお知らせすることが優先されます。 破壊的変更通知は、GitHub の Data API Builder リリースのリリース ノートと、専用の 破壊的変更リストの記事で確認できます。
現在の破壊的変更リスト
この記事では、破壊的変更と機能の廃止についてお知らせします。
- 現時点では、破壊的変更はありません