[インデックス 16276] ファイルの概要
このコミットは、Go言語の標準ライブラリの公開API定義を管理するシステムにおける重要な更新を示しています。具体的には、次期リリースであるGo 1.1のAPI定義をapi/go1.1.txt
として追加し、これまでの開発版APIを定義していたapi/next.txt
を削除しています。これに伴い、APIの互換性チェックを行うcmd/api
ツールが、新しいgo1.1.txt
ファイルを使用するように更新されています。この変更は、Go 1.1のリリースに向けたAPIの凍結と安定化のプロセスの一環です。
コミット
commit 9e93d5014e6a2e0ef9daf89489c7b12531fc95f3
Author: Brad Fitzpatrick <bradfitz@golang.org>
Date: Mon May 6 17:25:09 2013 -0700
api: add go1.1.txt; update cmd/api to use it
R=golang-dev, adg, r
CC=golang-dev
https://golang.org/cl/9250043
GitHub上でのコミットページへのリンク
https://github.com/golang/go/commit/9e93d5014e6a2e0ef9daf89489c7b12531fc95f3
元コミット内容
api: add go1.1.txt; update cmd/api to use it
変更の背景
Go言語は、後方互換性を非常に重視しており、特に標準ライブラリの公開APIについては厳格な互換性ポリシーを維持しています。新しいメジャーバージョン(例: Go 1.x)がリリースされる際、そのバージョンで導入される新しいAPIや変更されたAPIは、api/goX.Y.txt
という形式のファイルに記録されます。このファイルは、GoのAPI互換性チェックツールであるcmd/api
によって参照され、将来のバージョンで意図しないAPIの変更が発生しないように監視されます。
これまでの開発サイクルでは、次期バージョンのAPIはapi/next.txt
というファイルで管理されていました。Go 1.1のリリースが近づき、APIが安定し凍結される段階に入ったため、next.txt
の内容を正式なgo1.1.txt
として保存し、cmd/api
ツールがこの新しいファイルを基準としてAPIのチェックを行うように更新する必要がありました。このコミットは、Go 1.1のリリース準備におけるAPIの「スナップショット」を取り、その後の開発がGo 1.1のAPI定義に準拠していることを保証するための重要なステップです。
前提知識の解説
GoのAPI互換性ポリシー
Go言語は「Go 1 Compatibility Promise」という強力な後方互換性保証を持っています。これは、Go 1.xのリリース間で、既存のGo 1プログラムが新しいGo 1.xリリースでコンパイルされ、変更なしで実行されることを保証するものです。この保証は、特に標準ライブラリの公開APIに適用されます。新しい関数、メソッド、型、定数などが追加されることはありますが、既存のAPIが削除されたり、シグネチャが変更されたりすることは原則としてありません。
api/*.txt
ファイルの役割
Goプロジェクトでは、標準ライブラリの公開APIをテキストファイルで管理しています。
api/goX.Y.txt
: 特定のGoバージョン(例:go1.0.txt
,go1.1.txt
)でリリースされた標準ライブラリの公開APIのリストです。これらのファイルは、そのバージョンのAPIの「公式な記録」として機能します。api/next.txt
: 次のメジャーリリースに向けて開発中のAPIのリストです。開発中に新しいAPIが追加されると、このファイルに追記されます。リリースが近づきAPIが凍結されると、このnext.txt
の内容が新しいgoX.Y.txt
としてコピーされ、next.txt
はクリアされるか、次の開発サイクルに向けて更新されます。
これらのファイルは、go/doc
パッケージのapi
サブパッケージによって生成・解析されます。
cmd/api
ツールの役割
cmd/api
は、Goの標準ライブラリの公開APIが、api/*.txt
ファイルに定義されている内容と一致しているかを検証するためのコマンドラインツールです。このツールは、GoのビルドプロセスやCI/CDパイプラインの一部として実行され、開発者が意図せずAPI互換性を破壊する変更をコミットしてしまうことを防ぎます。具体的には、現在のGoソースコードからAPI情報を抽出し、指定されたapi/*.txt
ファイルの内容と比較します。差異があればエラーとして報告し、API互換性が維持されていることを保証します。
技術的詳細
このコミットの主要な技術的変更は、Go 1.1のリリース準備に伴うAPI定義ファイルの切り替えと、それに追従するツールの更新です。
-
api/go1.1.txt
の追加:api/next.txt
に蓄積されていたGo 1.1で導入されるAPIの定義が、新たにapi/go1.1.txt
としてコミットされました。このファイルには、Go 1.1で追加された膨大な数の新しい関数、メソッド、型、定数などが網羅的にリストアップされています。これは、Go 1.1のAPIがこの時点で「凍結」され、これ以降は原則として変更されないことを意味します。
-
api/next.txt
の削除:api/next.txt
は、Go 1.1のAPIがgo1.1.txt
として正式に記録されたため、その役割を終えました。このファイルは削除され、次のGoのメジャーリリース(Go 1.2など)の開発が始まると、再び新しいAPIの変更を追跡するために利用されることになります。
-
src/cmd/api/goapi.go
の更新:cmd/api
ツールは、APIの互換性チェックを行う際に参照するAPI定義ファイルを変更する必要があります。このコミットでは、goapi.go
内のロジックが更新され、これまでのnext.txt
ではなく、新しく追加されたgo1.1.txt
を読み込むように修正されました。これにより、cmd/api
はGo 1.1の正式なAPI定義を基準として、今後のAPI変更を監視できるようになります。
-
src/run.bash
およびsrc/run.bat
の更新:- これらのスクリプトは、Goプロジェクトのテストやビルドプロセスの一部として実行されるもので、
cmd/api
ツールを呼び出すコマンドが含まれています。cmd/api
が参照するAPI定義ファイルが変更されたため、これらのスクリプト内の関連するコマンドライン引数や設定も、next.txt
からgo1.1.txt
へ適切に更新されました。これにより、自動化されたテスト環境でもGo 1.1のAPI互換性チェックが正しく機能するようになります。
- これらのスクリプトは、Goプロジェクトのテストやビルドプロセスの一部として実行されるもので、
この一連の変更は、Goのリリースサイクルにおける標準的な手順であり、APIの安定性と後方互換性を保証するための重要なプロセスです。
コアとなるコードの変更箇所
このコミットでは、主に以下のファイルが変更されています。
-
api/go1.1.txt
: 新規追加ファイル。Go 1.1の公開API定義が記述されています。--- /dev/null +++ b/api/go1.1.txt @@ -0,0 +1,1773 @@ +pkg archive/tar, const TypeGNULongLink ideal-char +pkg archive/tar, const TypeGNULongName ideal-char +pkg archive/tar, func FileInfoHeader(os.FileInfo, string) (*Header, error) ... (以下、Go 1.1で追加されたAPIの定義が続く)
-
api/next.txt
: 削除されたファイル。--- a/api/next.txt +++ /dev/dev/null @@ -1,1767 +0,0 @@ -pkg archive/tar, const TypeGNULongLink ideal-char -pkg archive/tar, const TypeGNULongName ideal-char ... (以下、Go 1.1のAPI定義であった内容が削除される)
-
src/cmd/api/goapi.go
:cmd/api
ツールのソースコード。API定義ファイルを読み込む部分が変更されています。--- a/src/cmd/api/goapi.go +++ b/src/cmd/api/goapi.go @@ -10,7 +10,7 @@ // This program reads the Go API from the Go source tree // and prints it in a compact form. // -// Usage: goapi [-next] [-except=file] +// Usage: goapi [-go1.1] [-except=file] // // The output is a sequence of lines, one per API element, like: // pkg archive/tar, const TypeGNULongLink ideal-char @@ -20,7 +20,7 @@ import ( "bytes" "flag" - "fmt" "go/ast" "go/build" "go/parser" @@ -32,7 +32,7 @@ "strings" ) -var next = flag.Bool("next", false, "use next.txt instead of go1.0.txt") +var go1_1 = flag.Bool("go1.1", false, "use go1.1.txt instead of go1.0.txt") var except = flag.String("except", "", "file of API elements to ignore") func main() { @@ -40,7 +40,7 @@ flag.Parse() var filename string - if *next { - filename = "next.txt" + if *go1_1 { + filename = "go1.1.txt" } else { filename = "go1.0.txt" }
-
src/run.bash
: テストスクリプト。cmd/api
の呼び出し部分が変更されています。--- a/src/run.bash +++ b/src/run.bash @@ -100,7 +100,7 @@ # Check that the API is unchanged. # This must be done before building the toolchain, # because the toolchain might change the API. - go tool api -next > api/current.txt + go tool api -go1.1 > api/current.txt diff -u api/go1.1.txt api/current.txt if [ $? -ne 0 ]; then echo "API differs. Please run 'go tool api -go1.1 > api/go1.1.txt' and commit the result." 1>&2
-
src/run.bat
: テストスクリプト(Windows用)。cmd/api
の呼び出し部分が変更されています。--- a/src/run.bat +++ b/src/run.bat @@ -100,7 +100,7 @@ :: Check that the API is unchanged. :: This must be done before building the toolchain, :: because the toolchain might change the API. - go tool api -next > api\current.txt + go tool api -go1.1 > api\current.txt diff -u api\go1.1.txt api\current.txt if %errorlevel% neq 0 ( echo API differs. Please run "go tool api -go1.1 > api\go1.1.txt" and commit the result. 1>&2
コアとなるコードの解説
src/cmd/api/goapi.go
の変更
このファイルは、GoのAPI互換性チェックツールであるcmd/api
の主要なロジックを含んでいます。
変更の核心は、コマンドライン引数と、それに基づいて読み込むAPI定義ファイルを切り替える部分です。
-
フラグの変更:
-var next = flag.Bool("next", false, "use next.txt instead of go1.0.txt") +var go1_1 = flag.Bool("go1.1", false, "use go1.1.txt instead of go1.0.txt")
これまで
next
というブーリアンフラグが、api/next.txt
を使用するかどうかを制御していました。このコミットでは、そのフラグがgo1_1
にリネームされ、説明も「go1.1.txt
をgo1.0.txt
の代わりに使う」という具体的なものに変更されました。これは、Go 1.1のリリースが確定し、next.txt
がgo1.1.txt
として固定されたことを反映しています。 -
ファイル名の選択ロジック:
- if *next { - filename = "next.txt" + if *go1_1 { + filename = "go1.1.txt" } else { filename = "go1.0.txt" }
この部分で、
cmd/api
が比較対象とするAPI定義ファイルのパスが決定されます。以前は-next
フラグが指定された場合にnext.txt
を、そうでなければgo1.0.txt
(Go 1の初期リリースAPI)を読み込んでいました。変更後は、-go1.1
フラグが指定された場合にgo1.1.txt
を読み込むようになり、Go 1.1のAPIを基準としたチェックが可能になりました。これにより、Go 1.1のAPIが正式に確立された後も、そのAPIに対する互換性が維持されているかを継続的に検証できるようになります。
src/run.bash
およびsrc/run.bat
の変更
これらのシェルスクリプトは、Goプロジェクトの自動テストスイートの一部として実行されます。特に、API互換性チェックは、新しい変更が既存のAPIを破壊していないことを確認するために、ビルドプロセスの早い段階で実行されます。
-
go tool api
コマンドの引数変更:- go tool api -next > api/current.txt + go tool api -go1.1 > api/current.txt
go tool api
コマンドは、Goのツールチェインに含まれるAPIチェックツールを呼び出します。以前は-next
引数を使用してapi/next.txt
を基準としていましたが、この変更により-go1.1
引数を使用するように切り替わりました。これにより、スクリプトが実行されるたびに、現在のソースコードのAPIがGo 1.1の正式なAPI定義(api/go1.1.txt
)と一致しているかどうかが検証されるようになります。 -
エラーメッセージの更新:
echo "API differs. Please run 'go tool api -go1.1 > api/go1.1.txt' and commit the result." 1>&2
APIの差異が検出された場合のエラーメッセージも、新しいフラグとファイル名に合わせて更新されています。これにより、開発者はAPIの変更があった場合に、どのコマンドを実行して
go1.1.txt
を更新すべきかが明確に指示されます。
これらの変更は、Go 1.1のリリースに向けたAPIの安定化と、その後の継続的な互換性保証のための基盤を固めるものです。
関連リンク
- Go 1 Compatibility Promise: Go言語の公式ドキュメントで、後方互換性保証について説明されています。
- Go 1.1 Release Notes: Go 1.1で導入された新機能や変更点に関する公式リリースノート。このコミットで定義されたAPIの多くがここで紹介されています。
go/doc/api
パッケージ: GoのAPI定義ファイルを扱うための内部パッケージ。cmd/api
ツール: GoのAPI互換性チェックツールに関する情報。
参考にした情報源リンク
- Go言語の公式ドキュメント
- GoプロジェクトのGitHubリポジトリのコミット履歴
- Goのコードレビューシステム (Gerrit) の関連する変更リスト (CL: Change-ID 9250043)