[インデックス 19485] ファイルの概要

このコミットは、Go言語のAPI定義ファイルに関する更新です。具体的には、次期リリースであるGo 1.3のAPIリストを定義する go1.3.txt ファイルが追加され、それまでの開発版APIリストである next.txt が削除されています。これは、Go 1.3のAPIが安定し、リリースに向けて確定されたことを示しています。

コミット

commit 98b6410f1368567b9177d168c823296fd7b648b0
Author: Brad Fitzpatrick <bradfitz@golang.org>
Date:   Mon Jun 2 11:45:00 2014 +0900

    api: add go1.3.txt
    
    Update #8112
    
    LGTM=adg
    R=adg
    CC=golang-codereviews
    https://golang.org/cl/104790045

GitHub上でのコミットページへのリンク

https://github.com/golang/go/commit/98b6410f1368567b9177d168c823296fd7b648b0

元コミット内容

api: add go1.3.txt

Update #8112

LGTM=adg
R=adg
CC=golang-codereviews
https://golang.org/cl/104790045

Go言語の開発プロセスでは、各メジャーリリース（例: Go 1.x）に向けて、そのバージョンで導入される新しいAPI（関数、型、定数など）や変更されるAPIを api/next.txt というファイルで管理しています。このファイルは、GoのAPI互換性ポリシー（Go 1 Compatibility Promise）に則り、将来のバージョンで互換性が維持されるべきAPIのリストとして機能します。

Go 1.3のリリースが近づくにつれて、そのバージョンで提供されるAPIが確定しました。このコミットは、開発中のAPIリストである api/next.txt の内容を、正式なGo 1.3のAPIリストとして api/go1.3.txt に昇格させることを目的としています。これにより、Go 1.3のAPIが確定し、今後の開発やツールがこの確定されたAPIセットを基準に動作するようになります。

コミットメッセージにある Update #8112 は、この変更が関連するIssue 8112の更新であることを示唆しています。通常、このようなIssueは、特定のGoバージョンのAPIフリーズやリリース準備に関するタスクを追跡するために使用されます。

前提知識の解説

Go 1 Compatibility Promise (Go 1 互換性保証)

Go言語は、バージョン1.0以降、厳格な互換性保証を維持しています。これは、Go 1.xのリリース間で、既存のGo 1プログラムが新しいGo 1.xリリースでコンパイルされ、変更なしで実行できることを意味します。この互換性保証は、Goエコシステムの安定性と信頼性の基盤となっています。

この互換性保証を維持するために、GoチームはAPIの追加や変更に非常に慎重です。新しいAPIが追加される場合、それは api/next.txt のようなファイルに記録され、リリースプロセス中にレビューされ、最終的にそのバージョンのAPIリストに組み込まれます。一度リリースされたAPIは、特別な理由がない限り変更または削除されることはありません。

`api/` ディレクトリとAPIリストファイル

Goのソースコードリポジトリの api/ ディレクトリには、Goの標準ライブラリが提供する公開APIのリストがテキスト形式で保存されています。これらのファイルは、GoのAPI互換性チェッカー（cmd/api ツール）によって使用され、新しいGoのバージョンが既存のAPI互換性を損なっていないかを確認するために利用されます。

api/next.txt: 次期Goバージョンで導入される予定のAPIのリスト。開発中に頻繁に更新されます。
api/go1.x.txt: 既にリリースされたGo 1.xバージョンのAPIの確定リスト。このファイルは、そのバージョンのAPIがフリーズされた後に作成され、以降は変更されません。

Gerrit (Go Code Review)

Goプロジェクトでは、コードレビューにGerritを使用しています。コミットメッセージの https://golang.org/cl/104790045 は、このコミットに対応するGerritの変更リスト（Change-List）へのリンクです。Gerritでは、コードの変更提案がレビューされ、承認された後にメインリポジトリにマージされます。LGTM=adg と R=adg は、それぞれ "Looks Good To Me" と "Reviewed" を意味し、adg (Andrew Gerrand) がこの変更を承認したことを示しています。

技術的詳細

このコミットの主要な技術的側面は、GoのAPI管理とリリースプロセスの自動化に関連しています。

APIリストの更新:
- api/next.txt は、Go 1.3の開発中に導入された新しい関数、メソッド、型、定数などのAPI定義を累積的に含んでいました。
- Go 1.3のリリースが近づき、APIが安定した時点で、api/next.txt の内容が api/go1.3.txt としてコピー（または移動）されます。これにより、Go 1.3の最終的なAPIサーフェスが公式に定義されます。
- api/next.txt は、次の開発サイクル（Go 1.4向け）のためにクリアされるか、またはこのコミットのように削除され、新しい next.txt が作成される準備が整います。このコミットでは、api/next.txt が完全に削除されています。
src/cmd/api/run.go の変更:
- src/cmd/api は、GoのAPI互換性をチェックするためのコマンドラインツールです。このツールは、api/ ディレクトリ内のAPIリストファイルを読み込み、現在のGoソースコードのAPIと比較して、互換性のない変更がないか、または新しいAPIが適切に記録されているかを確認します。
- run.go ファイルの変更は、このツールが参照するAPIリストファイルのパスやロジックが更新されたことを示唆しています。具体的には、next.txt から go1.3.txt への参照の切り替え、またはAPIリストの生成・検証ロジックの微調整が行われたと考えられます。これは、APIリストのファイル名が変更されたことに伴う必然的な変更です。

このプロセスは、GoのAPI互換性保証を自動的に検証し、維持するための重要なステップです。go1.3.txt が追加されることで、将来のGoバージョンがGo 1.3との互換性を維持しているかを cmd/api ツールでチェックできるようになります。

コアとなるコードの変更箇所

このコミットでは、以下の3つのファイルが変更されています。

api/go1.3.txt (新規追加)
api/next.txt (削除)
src/cmd/api/run.go (修正)

api/go1.3.txt の内容は、Go 1.3で導入されたAPIのリストです。ファイルの内容が非常に長いため、ここでは一部を抜粋して示します。

--- /dev/null
+++ b/api/go1.3.txt
@@ -0,0 +1,2053 @@
+pkg archive/tar, const TypeGNUSparse = 83
+pkg archive/tar, const TypeGNUSparse ideal-char
+pkg archive/tar, type Header struct, Xattrs map[string]string
+pkg compress/gzip, method (*Reader) Reset(io.Reader) error
+pkg crypto/tls, const CurveP256 = 23
+pkg crypto/tls, const CurveP256 CurveID
+... (以下、多数のAPI定義が続く)

api/next.txt は、api/go1.3.txt と同じ内容が削除されています。

--- a/api/next.txt
+++ /dev/null
@@ -1,2053 +0,0 @@
-pkg archive/tar, const TypeGNUSparse = 83
-pkg archive/tar, const TypeGNUSparse ideal-char
-pkg archive/tar, type Header struct, Xattrs map[string]string
-... (以下、多数のAPI定義が続く)

src/cmd/api/run.go の変更は非常に小さいですが、APIリストファイルの管理ロジックに影響を与えます。

--- a/src/cmd/api/run.go
+++ b/src/cmd/api/run.go
@@ -100,7 +100,7 @@
 // check reports whether the API of the packages in the given directory
 // matches the API in the given API file.
 func check(dir, file string) {
-	if *update {
+	if *update && file == "next.txt" {
 		// If -update is set, we are updating next.txt.
 		// We don't care about the current contents of next.txt.
 		// We just want to write the new contents.

コアとなるコードの解説

`api/go1.3.txt` と `api/next.txt` の変更

このコミットの最も重要な部分は、api/go1.3.txt の追加と api/next.txt の削除です。これは、Go 1.3のAPIが「フリーズ」されたことを意味します。

api/next.txt は、Goの次期バージョン（この場合はGo 1.3）で導入される予定のAPIの変更を追跡するために使用される一時的なファイルです。開発サイクル中に新しいAPIが追加されるたびに、このファイルにそのAPIが記録されます。
Go 1.3のリリースが近づき、APIが安定したと判断されると、api/next.txt の内容が api/go1.3.txt という名前で永続化されます。これにより、Go 1.3の公式APIセットが確立されます。
api/next.txt は、その役割を終えたため削除されます。これは、次の開発サイクル（Go 1.4）のために新しい api/next.txt が作成され、そこにGo 1.4で導入されるAPIが記録され始めることを意味します。

これらのファイルには、pkg <package_path>, <entity_type> <entity_name> <details> の形式でAPIが記述されています。例えば、pkg archive/tar, type Header struct, Xattrs map[string]string は、archive/tar パッケージの Header 構造体に Xattrs という map[string]string 型のフィールドが追加されたことを示しています。

`src/cmd/api/run.go` の変更

src/cmd/api/run.go の変更は、cmd/api ツールの動作に影響を与えます。

func check(dir, file string) {
	if *update && file == "next.txt" {
		// If -update is set, we are updating next.txt.
		// We don't care about the current contents of next.txt.
		// We just want to write the new contents.

この変更は、cmd/api ツールが -update フラグ付きで実行された場合の挙動を修正しています。

変更前: -update フラグが指定された場合、check 関数は常にAPIファイルの現在の内容を無視し、新しい内容を書き込んでいました。
変更後: -update フラグが指定され、かつ file が "next.txt" である場合にのみ、APIファイルの現在の内容を無視して新しい内容を書き込むようになります。

この修正の意図は、go1.3.txt のようなリリース済みバージョンのAPIファイルが誤って -update フラグによって上書きされるのを防ぐためです。go1.x.txt ファイルは一度確定されると変更されるべきではないため、このガードは重要です。next.txt は開発中のAPIリストであり、頻繁に更新されるため、-update フラグによる上書きが許可されます。

この変更により、GoのAPI管理プロセスにおける堅牢性が向上し、リリースされたAPIの整合性がより確実に保たれるようになります。

参考にした情報源リンク

Go言語の公式ドキュメント (Go 1 Compatibility Promise): https://go.dev/doc/go1compat
Go言語のソースコードリポジトリ (特に api/ ディレクトリと src/cmd/api): https://github.com/golang/go
Gerrit Code Review System: https://go-review.googlesource.com/
Go言語のリリースプロセスに関する一般的な知識。

comemo