Keyboard shortcuts

Press or to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

[インデックス 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定義ファイルの切り替えと、それに追従するツールの更新です。

  1. api/go1.1.txtの追加:

    • api/next.txtに蓄積されていたGo 1.1で導入されるAPIの定義が、新たにapi/go1.1.txtとしてコミットされました。このファイルには、Go 1.1で追加された膨大な数の新しい関数、メソッド、型、定数などが網羅的にリストアップされています。これは、Go 1.1のAPIがこの時点で「凍結」され、これ以降は原則として変更されないことを意味します。
  2. api/next.txtの削除:

    • api/next.txtは、Go 1.1のAPIがgo1.1.txtとして正式に記録されたため、その役割を終えました。このファイルは削除され、次のGoのメジャーリリース(Go 1.2など)の開発が始まると、再び新しいAPIの変更を追跡するために利用されることになります。
  3. src/cmd/api/goapi.goの更新:

    • cmd/apiツールは、APIの互換性チェックを行う際に参照するAPI定義ファイルを変更する必要があります。このコミットでは、goapi.go内のロジックが更新され、これまでのnext.txtではなく、新しく追加されたgo1.1.txtを読み込むように修正されました。これにより、cmd/apiはGo 1.1の正式なAPI定義を基準として、今後のAPI変更を監視できるようになります。
  4. src/run.bashおよびsrc/run.batの更新:

    • これらのスクリプトは、Goプロジェクトのテストやビルドプロセスの一部として実行されるもので、cmd/apiツールを呼び出すコマンドが含まれています。cmd/apiが参照するAPI定義ファイルが変更されたため、これらのスクリプト内の関連するコマンドライン引数や設定も、next.txtからgo1.1.txtへ適切に更新されました。これにより、自動化されたテスト環境でもGo 1.1のAPI互換性チェックが正しく機能するようになります。

この一連の変更は、Goのリリースサイクルにおける標準的な手順であり、APIの安定性と後方互換性を保証するための重要なプロセスです。

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

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

  1. 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の定義が続く)
    
  2. 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定義であった内容が削除される)
    
  3. 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"
     	}
    
  4. 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
    
  5. 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.txtgo1.0.txtの代わりに使う」という具体的なものに変更されました。これは、Go 1.1のリリースが確定し、next.txtgo1.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)