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

このコミットは、Go言語の標準ライブラリの次期リリースで導入される予定のAPI変更を記録するapi/next.txtファイルを更新するものです。過去数週間にわたる蓄積された変更を反映し、all.bashスクリプトの出力がクリーンになるように調整されています。

コミット

commit ccbac5a48025a5ad911fa1a02e43486043c89038
Author: Brad Fitzpatrick <bradfitz@golang.org>
Date:   Sat Jun 30 12:25:38 2012 -0700

    api: update next.txt
    
    Some accumulated changes from the past few weeks.
    
    Just cleans up all.bash output.
    
    R=golang-dev, adg
    CC=golang-dev
    https://golang.org/cl/6354056

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

https://github.com/golang/go/commit/ccbac5a48025a5ad911fa1a02e43486043c89038

元コミット内容

このコミットの目的は、Go標準ライブラリのAPI定義ファイルであるapi/next.txtを更新することです。これは、過去数週間にわたって蓄積されたAPIの変更を反映し、ビルドスクリプト（all.bash）の出力がより整理されるようにするためのものです。

変更の背景

Go言語の開発プロセスでは、標準ライブラリのAPI変更は厳格に管理されています。api/next.txtファイルは、次期リリースで導入される予定の新しいAPI、変更されるAPI、または削除されるAPIを一覧で記録するためのものです。このファイルは、APIの安定性を保証し、後方互換性の問題を早期に特定するために重要な役割を果たします。

このコミットが行われた背景には、以下の理由が考えられます。

APIの蓄積: 開発サイクル中に、様々な機能追加や改善に伴い、多くの新しいAPIが追加されたり、既存のAPIが変更されたりします。これらの変更は、定期的にapi/next.txtに反映される必要があります。
all.bash出力のクリーンアップ: all.bashはGoプロジェクトの主要なビルドおよびテストスクリプトです。このスクリプトは、APIの変更を検出して報告する機能を含んでいる場合があります。api/next.txtが実際のAPIの状態と同期していない場合、all.bashの実行時に不要な警告やエラーが出力される可能性があります。このコミットは、そのような「ノイズ」を排除し、開発者が重要な情報に集中できるようにすることを目的としています。
APIレビュープロセス: GoのAPI変更は、通常、Gerritなどのコードレビューシステムを通じて厳密なレビューを受けます。api/next.txtの更新は、これらのレビューが完了し、APIが安定版として受け入れられる準備ができたことを示す最終ステップの一部であることがあります。

前提知識の解説

`api/next.txt`とは

api/next.txtは、Go言語の標準ライブラリにおいて、次期メジャーリリースで導入される予定のAPIの変更（追加、変更、削除）を記録するためのテキストファイルです。このファイルは、GoのAPI互換性保証の一部として非常に重要です。

目的: Goは「Go 1互換性保証」を掲げており、Go 1.xリリース間での後方互換性を厳密に維持しています。しかし、新しい機能の追加や改善のためにAPIを変更する必要がある場合もあります。api/next.txtは、これらの変更を事前に文書化し、開発者コミュニティが次期リリースで何が変更されるかを把握できるようにするために使用されます。
内容: ファイルには、パッケージ名、型、関数、メソッド、定数などのAPI要素が、その種類（pkg、type、func、method、constなど）とともに記述されます。
生成と検証: このファイルは手動で編集されることもありますが、通常はGoのツール（例: go tool api）によって生成または検証されます。ビルドプロセスの一部として、実際のAPIとapi/next.txtの内容が一致しているかどうかがチェックされます。不一致がある場合、ビルドエラーや警告が発生し、開発者はファイルを更新するか、APIの変更を再検討する必要があります。

GoのAPIレビュープロセスとGerrit

Go言語のプロジェクトでは、コード変更、特にAPIの変更に対して厳格なレビュープロセスが適用されます。

Gerrit: Goプロジェクトは、コードレビューにGerritというシステムを使用しています。開発者は変更をGerritにアップロードし、他の開発者（レビュアー）がその変更をレビューします。レビュープロセスでは、コードの品質、設計、パフォーマンス、そしてAPIの互換性などが評価されます。
Change-ID (golang.org/cl/): コミットメッセージに含まれるhttps://golang.org/cl/6354056のようなリンクは、Gerrit上の特定の変更セット（Change-ID）を指します。これは、そのコミットがどのレビュープロセスを経て承認されたかを示すものです。

技術的詳細

このコミットは、api/next.txtファイルに複数の新しいAPI要素の追加と、いくつかの既存エントリの削除を記録しています。これは、Go標準ライブラリの進化を反映しています。

追加されたAPI要素

pkg crypto/x509:
- const ExtKeyUsageIPSECEndSystem ExtKeyUsage
- const ExtKeyUsageIPSECTunnel ExtKeyUsage
- const ExtKeyUsageIPSECUser ExtKeyUsage
  - これらはX.509証明書の拡張鍵用途（Extended Key Usage, EKU）に関する定数です。IPsec（Internet Protocol Security）に関連する用途が追加されたことを示します。これにより、IPsec通信における証明書の利用シナリオがより詳細に定義できるようになります。
- const IncompatibleUsage InvalidReason
  - 証明書の検証失敗理由の一つとして、用途の不適合を示す定数が追加されました。
- type VerifyOptions struct, KeyUsages []ExtKeyUsage
  - 証明書検証オプション構造体VerifyOptionsに、検証時に考慮すべき拡張鍵用途のリストKeyUsagesが追加されました。これにより、特定の用途に限定した証明書検証が可能になります。
pkg encoding/json:
- method (*Decoder) UseNumber()
  - json.DecoderがJSONの数値をデフォルトのfloat64ではなく、json.Number型としてデコードするように設定するメソッドです。これにより、数値の精度を失うことなく、文字列として保持したり、後でint64やfloat64に変換したりする柔軟性が提供されます。
- method (Number) Float64() (float64, error)
- method (Number) Int64() (int64, error)
- method (Number) String() string
- type Number string
  - json.Number型が導入され、その操作メソッドが追加されました。これはJSONの数値を文字列として表現し、必要に応じてfloat64やint64に変換できる機能を提供します。これにより、JavaScriptの数値表現の限界（IEEE 754倍精度浮動小数点数）を超える大きな整数や、厳密な数値表現が必要な場合に役立ちます。
pkg go/ast:
- func NewCommentMap(*token.FileSet, Node, []*CommentGroup) CommentMap
- method (CommentMap) Comments() []*CommentGroup
- method (CommentMap) Filter(Node) CommentMap
- method (CommentMap) String() string
- method (CommentMap) Update(Node) Node
- type CommentMap map[Node][]*CommentGroup
  - Goの抽象構文木（AST）において、コメントをASTノードに関連付けるためのCommentMap型とその関連関数・メソッドが追加されました。これにより、Goのソースコードを解析するツールが、コードとコメントの関連性をより正確に把握し、操作できるようになります。例えば、リファクタリングツールやコード生成ツールがコメントを適切に保持するために利用されます。
pkg image:
- const YCbCrSubsampleRatio440 YCbCrSubsampleRatio
  - YCbCr色空間におけるサブサンプリング比率の定数が追加されました。これは、JPEGなどの画像フォーマットで色情報を効率的に表現するために使用されます。4:4:0は、輝度情報（Y）はフル解像度で、色差情報（CbとCr）は垂直方向に半分にサンプリングされることを意味します。
pkg net/http:
- method (*Request) PostFormValue(string) string
  - HTTP POSTリクエストのフォームデータから、指定されたキーに対応する単一の値を返す便利なメソッドが追加されました。これは、Request.ParseForm()を呼び出した後、Request.PostFormマップから値を取得する手間を省きます。
- type Request struct, PostForm url.Values
  - http.Request構造体にPostFormフィールドが追加されました。これは、POSTリクエストのボディからパースされたフォームデータを保持します。
pkg net/textproto:
- func TrimBytes([]byte) []byte
- func TrimString(string) string
  - バイトスライスまたは文字列の先頭と末尾から空白文字をトリムする関数が追加されました。これは、HTTPヘッダーやメールのヘッダーなど、テキストベースのプロトコルでよく見られる空白文字の処理を簡素化します。
pkg syscall (freebsd-amd64):
- func Syscall9(uintptr) (uintptr, Errno)
  - FreeBSD/amd64アーキテクチャ向けの9引数システムコール関数が追加されました。これは、特定のシステムコールを直接呼び出す必要がある場合に利用されます。

削除されたAPI要素

pkg regexp/syntax:
- const ErrUnexpectedParen ErrorCode
  - 正規表現の構文エラーコードErrUnexpectedParenが削除されました。これは、正規表現パーサーの改善により、この特定のエラーケースがより一般的なエラーに統合されたか、もはや発生しないようになったことを示唆しています。
pkg syscall (windows-386) / pkg syscall (windows-amd64):
- func GetCurrentProcessId() uint32
  - Windows向けのGetCurrentProcessId関数が削除されました。これは、Goの標準ライブラリ内でプロセスIDを取得するより一般的な方法（例: os.Getpid()）が提供されたため、またはこの低レベルなシステムコールが直接公開される必要がなくなったためと考えられます。

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

このコミットで変更されたファイルはapi/next.txtのみです。以下にその差分を示します。

--- a/api/next.txt
+++ b/api/next.txt
@@ -6,13 +6,33 @@ pkg crypto/x509, const ECDSAWithSHA1 SignatureAlgorithm
 pkg crypto/x509, const ECDSAWithSHA256 SignatureAlgorithm
 pkg crypto/x509, const ECDSAWithSHA384 SignatureAlgorithm
 pkg crypto/x509, const ECDSAWithSHA512 SignatureAlgorithm
+pkg crypto/x509, const ExtKeyUsageIPSECEndSystem ExtKeyUsage
+pkg crypto/x509, const ExtKeyUsageIPSECTunnel ExtKeyUsage
+pkg crypto/x509, const ExtKeyUsageIPSECUser ExtKeyUsage
+pkg crypto/x509, const IncompatibleUsage InvalidReason
+pkg crypto/x509, type VerifyOptions struct, KeyUsages []ExtKeyUsage
 pkg debug/elf, type FileHeader struct, Entry uint64
+pkg encoding/json, method (*Decoder) UseNumber()
+pkg encoding/json, method (Number) Float64() (float64, error)
+pkg encoding/json, method (Number) Int64() (int64, error)
+pkg encoding/json, method (Number) String() string
+pkg encoding/json, type Number string
+pkg go/ast, func NewCommentMap(*token.FileSet, Node, []*CommentGroup) CommentMap
+pkg go/ast, method (CommentMap) Comments() []*CommentGroup
+pkg go/ast, method (CommentMap) Filter(Node) CommentMap
+pkg go/ast, method (CommentMap) String() string
+pkg go/ast, method (CommentMap) Update(Node) Node
+pkg go/ast, type CommentMap map[Node][]*CommentGroup
 pkg go/doc, var IllegalPrefixes []string
+pkg image, const YCbCrSubsampleRatio440 YCbCrSubsampleRatio
 pkg math/big, method (*Int) MarshalJSON() ([]byte, error)
 pkg math/big, method (*Int) UnmarshalJSON([]byte) error
 pkg net, method (*UnixConn) CloseRead() error
 pkg net, method (*UnixConn) CloseWrite() error
-pkg regexp/syntax, const ErrUnexpectedParen ErrorCode
+pkg net/http, method (*Request) PostFormValue(string) string
+pkg net/http, type Request struct, PostForm url.Values
+pkg net/textproto, func TrimBytes([]byte) []byte
+pkg net/textproto, func TrimString(string) string
 pkg syscall (darwin-386), const B0 ideal-int
 pkg syscall (darwin-386), const B110 ideal-int
 pkg syscall (darwin-386), const B115200 ideal-int
@@ -419,15 +439,14 @@ pkg syscall (darwin-amd64-cgo), type Termios struct, Lflag uint64
 pkg syscall (darwin-amd64-cgo), type Termios struct, Oflag uint64
 pkg syscall (darwin-amd64-cgo), type Termios struct, Ospeed uint64
 pkg syscall (darwin-amd64-cgo), type Termios struct, Pad_cgo_0 [4]byte
+pkg syscall (freebsd-amd64), func Syscall9(uintptr) (uintptr, Errno)
 pkg syscall (windows-386), const CREATE_NEW_PROCESS_GROUP ideal-int
 pkg syscall (windows-386), const CTRL_BREAK_EVENT ideal-int
 pkg syscall (windows-386), const CTRL_C_EVENT ideal-int
-pkg syscall (windows-386), func GetCurrentProcessId() uint32
 pkg syscall (windows-386), func Getsockopt(Handle, int32, int32, *byte, *int32) error
 pkg syscall (windows-386), type SysProcAttr struct, CreationFlags uint32
 pkg syscall (windows-amd64), const CREATE_NEW_PROCESS_GROUP ideal-int
 pkg syscall (windows-amd64), const CTRL_BREAK_EVENT ideal-int
 pkg syscall (windows-amd64), const CTRL_C_EVENT ideal-int
-pkg syscall (windows-amd64), func GetCurrentProcessId() uint32
 pkg syscall (windows-amd64), func Getsockopt(Handle, int32, int32, *byte, *int32) error
 pkg syscall (windows-amd64), type SysProcAttr struct, CreationFlags uint32

コアとなるコードの解説

この差分は、Go標準ライブラリのAPIがどのように進化しているかを示しています。

緑色の行（+で始まる行）: これらは新しく追加されたAPI要素です。例えば、pkg crypto/x509の下に追加されたIPsec関連のExtKeyUsage定数や、encoding/jsonパッケージのNumber型とそのメソッド群、go/astのCommentMap関連のAPIなどがこれに該当します。これらの追加は、Goの機能が拡張され、より多様なユースケースに対応できるようになっていることを意味します。
赤色の行（-で始まる行）: これらは削除されたAPI要素です。regexp/syntaxのErrUnexpectedParenや、Windows向けのsyscall.GetCurrentProcessId()が削除されています。APIの削除は、通常、より良い代替手段が提供された、APIが不要になった、または設計上の理由で変更されたことを意味します。

このファイルは、GoのAPI互換性保証の重要な部分であり、Goの次期リリースで利用可能になるAPIの「スナップショット」を提供します。開発者はこのファイルを参照することで、将来のGoバージョンで利用できる新しい機能や、非推奨となる可能性のあるAPIを事前に把握できます。

参考にした情報源リンク

Go言語の公式ドキュメント (各パッケージのドキュメント)
Go言語のAPI互換性に関する情報
Gerrit Code Review (GoプロジェクトのGerritインスタンス)
api/next.txtの役割に関するGoコミュニティの議論

comemo