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

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

コミット

commit 04e95a1a56c35f63e3ac51c9d9973297a57c2b10
Author: Andrew Gerrand <adg@golang.org>
Date:   Fri Oct 18 13:36:59 2013 +0900

    api: add go1.2.txt, use in tests

    R=golang-dev, iant
    CC=golang-dev
    https://golang.org/cl/14860043

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

https://github.com/golang/go/commit/04e95a1a56c35f63e3ac51c9d9973297a57c2b10

元コミット内容

このコミットは、Go言語のAPI定義ファイルに関するものです。具体的には、api/go1.2.txtという新しいファイルを追加し、既存のapi/next.txtファイルを削除しています。この変更は、Go 1.2リリースに向けたAPIの確定と、テストにおけるそのAPI定義の利用を目的としています。

ファイル変更の概要:

  • api/go1.2.txt: 新規追加 (32484行の挿入)
  • api/next.txt: 削除 (32479行の削除)
  • src/cmd/api/run.go: 2行の変更 (1行の挿入、1行の削除)

変更の背景

Go言語は、後方互換性を非常に重視しており、特に公開APIの変更には厳格なポリシーを持っています。メジャーリリース（例: Go 1.x）では、既存の公開APIを変更しないことが原則です。このコミットは、Go 1.2のリリースプロセスの一環として行われました。

Goプロジェクトでは、将来のリリースで導入される可能性のあるAPI変更を追跡するために、api/next.txtのようなファイルを使用していました。これは、開発中のAPIサーフェスを記録し、互換性に関する問題を早期に特定するためのものです。

Go 1.2のリリースが近づくにつれて、そのバージョンで提供されるAPIセットが確定されます。この確定されたAPIセットは、go1.2.txtのようなバージョン固有のファイルに記録されます。このファイルは、Go 1.2の公開APIの「スナップショット」として機能し、Go 1.2の互換性保証の基盤となります。

したがって、このコミットの背景には、Go 1.2のAPIフリーズ（APIの確定）があり、開発中のAPI定義から安定版のAPI定義への移行が行われたことを示しています。また、src/cmd/api/run.goの変更は、APIテストツールがこの新しいgo1.2.txtファイルを使用するように更新されたことを意味します。

前提知識の解説

このコミットを理解するためには、以下のGo言語およびソフトウェア開発における一般的な概念に関する知識が必要です。

  1. Go言語のAPI互換性保証 (Go 1 Compatibility Promise): Go言語は、バージョン1.xのリリースにおいて、非常に強力な後方互換性保証を提供しています。これは、Go 1で書かれたプログラムは、Go 1.xの将来のバージョンでもコンパイルされ、動作し続けることを意味します。この保証は、Goエコシステムの安定性と信頼性の基盤となっています。この互換性保証の重要な側面の一つが、公開API（エクスポートされた関数、型、メソッド、定数など）の変更を最小限に抑えることです。

  2. API定義ファイル (api/*.txt): Goプロジェクトでは、標準ライブラリの公開APIをテキストファイルとして記録しています。これらのファイルは通常、api/go1.x.txt（特定のバージョンで安定したAPI）やapi/next.txt（次のリリースで導入される可能性のあるAPI）のような命名規則に従います。これらのファイルは、cmd/apiツールによって生成および検証されます。

    • api/next.txt: 開発中のAPI変更を追跡するためのファイル。新しいAPIが追加されたり、既存のAPIが変更されたりすると、このファイルが更新されます。
    • api/go1.x.txt: 特定のGoバージョン（例: Go 1.2）で安定したとみなされるAPIの最終的なセットを記録するファイル。このファイルに記載されたAPIは、そのバージョン以降のGo 1.xリリースで互換性が維持されることが期待されます。

  3. APIフリーズ (API Freeze): ソフトウェア開発における「APIフリーズ」とは、特定のリリースに向けてAPIの変更を停止する期間を指します。この期間中、新しいAPIの追加や既存APIの変更は原則として行われず、APIの安定化とバグ修正に焦点が当てられます。Go言語のリリースサイクルにおいても、APIフリーズは重要なマイルストーンであり、その後のテストと品質保証の段階に進むための準備となります。

  4. cmd/api ツール: Goのソースコードリポジトリには、src/cmd/apiというディレクトリにAPI定義を管理するためのツールが含まれています。このツールは、Goのソースコードを解析し、公開APIのリストを生成したり、既存のAPI定義ファイルとの差分を検出したりするのに使用されます。これにより、APIの意図しない変更や互換性の破壊を防ぐことができます。

技術的詳細

このコミットは、Go 1.2のリリース準備におけるAPI管理の具体的なステップを示しています。

  1. api/go1.2.txt の追加: このファイルは、Go 1.2で導入される新しい公開API、およびGo 1.1以前から存在するがGo 1.2で変更がない公開APIの完全なリストを含んでいます。ファイルの内容は、pkg <パッケージ名>, <要素の種類> <要素名> の形式で、Go標準ライブラリの各パッケージがエクスポートする関数、メソッド、型、定数、変数などを網羅しています。例えば、pkg archive/zip, func RegisterCompressor(uint16, Compressor) は、archive/zipパッケージにRegisterCompressorという関数が追加されたことを示しています。このファイルの追加は、Go 1.2のAPIが確定し、その後のリリースでこのAPIセットが後方互換性の対象となることを意味します。

  2. api/next.txt の削除: api/next.txtは、Go 1.2の開発中に将来のAPI変更を追跡するために使用されていたファイルです。Go 1.2のAPIがapi/go1.2.txtとして確定されたため、api/next.txtはもはや不要となり、削除されました。これは、開発中のAPIが安定版のAPIに昇格したことを象徴しています。

  3. src/cmd/api/run.go の変更: このファイルは、GoのAPIテストツールであるcmd/apiの一部です。変更内容は非常に小さいですが、これはcmd/apiツールがAPIの互換性チェックを行う際に、参照するAPI定義ファイルをapi/next.txtからapi/go1.2.txtに切り替えたことを示唆しています。具体的には、run.go内のロジックが、新しいバージョンのAPI定義ファイル（この場合はgo1.2.txt）を読み込むように更新されたと考えられます。これにより、Go 1.2のAPIが正式に「フリーズ」され、それ以降の変更は厳しく管理されるようになります。

この一連の変更は、GoのリリースプロセスにおけるAPIの安定化フェーズの典型的な例です。開発中のAPIが特定のバージョンに紐付けられ、そのバージョンでの互換性が保証されるための基盤が構築されます。

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

このコミットのコアとなる変更は、以下の3つのファイルに集中しています。

  1. api/go1.2.txt:

    • 新規追加されたファイル。
    • Go 1.2で公開されるAPIの定義が網羅的に記述されています。
    • 例: 
      +pkg archive/zip, func RegisterCompressor(uint16, Compressor)
+pkg archive/zip, func RegisterDecompressor(uint16, Decompressor)
+pkg archive/zip, method (*File) DataOffset() (int64, error)
...
+pkg crypto/cipher, func NewGCM(Block) (AEAD, error)
+pkg crypto/cipher, type AEAD interface { NonceSize, Open, Overhead, Seal }
...
+pkg runtime, type MemStats struct, GCSys uint64
+pkg runtime, type MemStats struct, OtherSys uint64
...
    • このファイルは、Go 1.2の公開APIサーフェスを定義するものであり、その後のGo 1.xリリースにおける後方互換性の基準となります。

  2. api/next.txt:

    • 完全に削除されたファイル。
    • Go 1.2の開発中に、将来のAPI変更を追跡するために使用されていました。
    • このファイルの削除は、Go 1.2のAPIが確定し、go1.2.txtにその役割が引き継がれたことを意味します。

  3. src/cmd/api/run.go:

    • APIテストツールcmd/apiの実行ロジックが含まれるファイル。
    • 具体的な変更内容はコミットログからは読み取れませんが、2 +-, 32485 insertions(+), 32480 deletions(-)という行数から、api/go1.2.txtの追加とapi/next.txtの削除が主要な変更であり、src/cmd/api/run.goの変更は、API定義ファイルの参照先をnext.txtからgo1.2.txtに切り替えるための微調整であると推測されます。

コアとなるコードの解説

このコミットにおける「コアとなるコード」は、Go言語のAPI定義そのものと、それを管理するツールの設定変更です。

api/go1.2.txt の内容: このファイルは、Go言語の標準ライブラリが提供する公開APIの「署名」の集合体です。各行は、特定のパッケージ内のエクスポートされた要素（関数、メソッド、型、定数、変数）を記述しています。

例: pkg crypto/cipher, type AEAD interface { NonceSize, Open, Overhead, Seal } これは、crypto/cipherパッケージにAEADというインターフェースが定義されており、そのインターフェースがNonceSize, Open, Overhead, Sealというメソッドを持つことを示しています。

このようなAPI定義ファイルは、以下の目的で利用されます。

  • 互換性チェック: cmd/apiツールは、現在のGoソースコードからAPI定義を抽出し、go1.x.txtファイルの内容と比較することで、意図しないAPIの変更や互換性の破壊がないかを自動的にチェックします。
  • ドキュメント生成: APIドキュメントの生成や、IDEでのコード補完などのツールが、これらの定義を利用することがあります。
  • リリース管理: 特定のGoバージョンで利用可能なAPIの公式な記録として機能します。

api/next.txt の削除: api/next.txtは、Go 1.2の開発中に、まだ確定していないAPI変更を一時的に記録するための「ステージングエリア」のような役割を果たしていました。Go 1.2のAPIが確定し、go1.2.txtとして永続化されたため、next.txtは役割を終え、削除されました。これは、開発フェーズから安定化フェーズへの移行を示す明確なシグナルです。

src/cmd/api/run.go の変更 (推測): src/cmd/api/run.goは、cmd/apiコマンドの主要な実行ファイルです。このファイルは、Goのソースコードを解析し、API定義を抽出するロジックを含んでいます。このコミットでの変更は、おそらくcmd/apiツールがAPIの互換性チェックを行う際に、比較対象とする「基準となるAPIファイル」をapi/next.txtからapi/go1.2.txtに切り替えるためのものです。

例えば、内部的には以下のようなコード変更が行われた可能性があります（擬似コード）：

// 変更前:
// apiFile := "api/next.txt"

// 変更後:
apiFile := "api/go1.2.txt" // Go 1.2のAPIを基準とする

このような変更により、cmd/apiツールはGo 1.2のAPIフリーズを強制し、それ以降のGo 1.2ブランチへのコミットが、go1.2.txtで定義されたAPIとの互換性を維持しているかを検証するようになります。これにより、Go 1.2の安定性と後方互換性が保証されます。

関連リンク

参考にした情報源リンク