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

このコミットは、Go言語の公式ドキュメントの一部である doc/reference.html ファイルに、Goプロジェクトのサブリポジトリへのリンクを追加するものです。これにより、ユーザーはGoのコアツリー外で開発されている重要なパッケージ群に容易にアクセスできるようになります。

コミット

doc: link to sub-repositories from reference page

R=golang-dev, r
CC=golang-dev
https://golang.org/cl/5752049

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

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

元コミット内容

doc: link to sub-repositories from reference page

このコミットは、Go言語のドキュメントページにサブリポジトリへのリンクを追加することを目的としています。

変更の背景

Go言語のプロジェクトは、コアのGoツリー（標準ライブラリやツールなど）と、それとは別に開発・管理されている「サブリポジトリ」と呼ばれるパッケージ群で構成されています。これらのサブリポジトリは、Goのコアとは異なる、より緩やかな互換性要件の下で開発されており、go get コマンドで取得・インストールすることが推奨されています。

このコミットが行われた2012年3月時点では、Go言語はまだ比較的新しい言語であり、そのエコシステムは急速に拡大していました。ユーザーがGoのサブリポジトリの存在を認識し、それらにアクセスするための明確な参照点を提供することは、ドキュメントの利便性と発見性を向上させる上で重要でした。

この変更の背景には、以下の目的があったと考えられます。

1. 発見性の向上: ユーザーがGoのサブリポジトリの存在を知り、それらのパッケージを容易に見つけられるようにする。
2. ドキュメントの網羅性: Goプロジェクト全体をカバーするドキュメントの一部として、サブリポジトリに関する情報を含める。
3. 利用促進: go get コマンドによるサブリポジトリのインストール方法を明示することで、ユーザーによる利用を促進する。
4. 互換性要件の明確化: サブリポジトリがGoコアとは異なる互換性要件（go1compat.html で説明されている）を持つことを明確に伝える。

前提知識の解説

Go言語のサブリポジトリ

Go言語のサブリポジトリ（またはエクスペリメンタルリポジトリ）は、Goプロジェクトの一部として開発されていますが、Goの標準ライブラリやツールとは異なり、独立したバージョン管理とリリースサイクルを持っています。これらは通常、Goのコアツリーには含まれないが、Goエコシステムにとって有用な機能やパッケージを提供します。例えば、暗号化、画像処理、ネットワーク関連の高度な機能などが含まれることがあります。

サブリポジトリは、Goのコアの安定性を保ちつつ、新しいアイデアや実験的な機能を導入するための柔軟な場として機能します。そのため、Goのコアに比べてAPIの変更や非互換性が導入される可能性が若干高い場合がありますが、それでもGoチームによって管理され、品質が保証されています。

go get コマンド

go get は、Go言語のパッケージ管理ツールであり、指定されたパッケージのソースコードをダウンロードし、依存関係を解決し、必要に応じてビルドしてインストールするコマンドです。Goのモジュールシステムが導入される前は、主にこのコマンドが外部パッケージの取得に使用されていました。

例えば、go get code.google.com/p/go.crypto のように実行することで、go.crypto サブリポジトリのパッケージをローカル環境にダウンロードし、利用可能にすることができます。

doc/reference.html

doc/reference.html は、Go言語の公式ドキュメントサイト（golang.org/doc）の一部であり、Go言語の参照情報や主要なドキュメントへのリンクがまとめられているページです。このページは、Go言語の全体像を把握したり、特定のドキュメントを探したりする際の入り口となる重要な役割を担っています。

Go 1 Compatibility Promise (go1compat.html)

Go 1 Compatibility Promiseは、Go 1リリース以降のGo言語の安定性と後方互換性に関するGoチームのコミットメントを説明するドキュメントです。これは、Go 1で導入されたAPIは、将来のGoのバージョンでも互換性が維持されることを保証するもので、Goエコシステムの安定した発展を支える基盤となっています。サブリポジトリは、このGo 1互換性要件がコアライブラリほど厳密に適用されない場合があるため、その旨が明記されています。

技術的詳細

このコミットは、doc/reference.html ファイルにHTMLコードを追加することで、サブリポジトリへのリンクセクションを導入しています。具体的には、以下のHTML要素が追加されています。

1. 見出し (<h4>):

   <h4 id="subrepos">Sub-repositories</h4>
   

   id="subrepos" を持つ <h4> タグが追加され、「Sub-repositories」という新しいセクション見出しが作成されています。これにより、ページ内リンクからの直接アクセスが可能になります。

2. 説明段落 (<p>):

   <p>
   These packages are part of the Go Project but outside the main Go tree.
   They are developed under looser <a href="/doc/go1compat.html">compatibility
   requirements</a> than the Go core.
   Install them with "<code><a href="/cmd/go/#Download_and_install_packages_and_dependencies">go get</a></code>".
   </p>
   

   サブリポジトリの性質（Goプロジェクトの一部だがメインツリー外であること、緩やかな互換性要件を持つこと）を説明する段落が追加されています。

   • 「compatibility requirements」の部分には、Go 1互換性に関するドキュメント go1compat.html へのリンクが埋め込まれています。
   • 「go get」の部分には、go コマンドのドキュメント内の「Download and install packages and dependencies」セクションへのリンクが埋め込まれており、サブリポジトリのインストール方法をユーザーに案内しています。<code> タグでコマンドが視覚的に強調されています。

3. サブリポジトリのリスト (<ul> と <li>):

   <ul>
   <li><a href="http://code.google.com/p/go/source/browse?repo=codereview"><code>code.google.com/p/go.codereview</code></a> [<a href="http://gopkgdoc.appspot.com/pkg/code.google.com/p/go.codereview">docs</a>]
   <li><a href="http://code.google.com/p/go/source/browse?repo=crypto"><code>code.google.com/p/go.crypto</code></a> [<a href="http://gopkgdoc.appspot.com/pkg/code.google.com/p/go.crypto">docs</a>]
   <li><a href="http://code.google.com/p/go/source/browse?repo=image"><code>code.google.com/p/go.image</code></a> [<a href="http://gopkgdoc.appspot.com/pkg/code.google.com/p/go.image">docs</a>]
   <li><a href="http://code.google.com/p/go/source/browse?repo=net"><code>code.google.com/p/go.net</code></a> [<a href="http://gopkgdoc.appspot.com/pkg/code.google.com/p/go.net">docs</a>]
   </ul>
   

   主要なサブリポジトリへのリンクを含む順序なしリストが追加されています。各リストアイテム (<li>) には、以下の2つのリンクが含まれています。

   • ソースコードリポジトリへのリンク: http://code.google.com/p/go/source/browse?repo=... の形式で、各サブリポジトリのソースコードブラウザへのリンクが提供されています。パッケージ名自体も <code> タグで囲まれ、視覚的に区別されています。
   • パッケージドキュメントへのリンク: http://gopkgdoc.appspot.com/pkg/... の形式で、各サブリポジトリの gopkgdoc.appspot.com 上のドキュメントページへのリンクが提供されています。これは、当時のGoパッケージドキュメントの主要なホスティングサービスでした。

この変更は、既存のHTML構造に新しいセクションを挿入する形で行われており、ページのレイアウトや既存のコンテンツに大きな影響を与えることなく、新しい情報が追加されています。

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

--- a/doc/reference.html
+++ b/doc/reference.html
@@ -14,6 +14,22 @@
 The documentation for the Go standard library.
 </p>
 
+<h4 id="subrepos">Sub-repositories</h4>
+
+<p>
+These packages are part of the Go Project but outside the main Go tree.
+They are developed under looser <a href="/doc/go1compat.html">compatibility
+requirements</a> than the Go core.
+Install them with "<code><a href="/cmd/go/#Download_and_install_packages_and_dependencies">go get</a></code>".
+</p>
+
+<ul>
+<li><a href="http://code.google.com/p/go/source/browse?repo=codereview"><code>code.google.com/p/go.codereview</code></a> [<a href="http://gopkgdoc.appspot.com/pkg/code.google.com/p/go.codereview">docs</a>]\n
+<li><a href="http://code.google.com/p/go/source/browse?repo=crypto"><code>code.google.com/p/go.crypto</code></a> [<a href="http://gopkgdoc.appspot.com/pkg/code.google.com/p/go.crypto">docs</a>]\n
+<li><a href="http://code.google.com/p/go/source/browse?repo=image"><code>code.google.com/p/go.image</code></a> [<a href="http://gopkgdoc.appspot.com/pkg/code.google.com/p/go.image">docs</a>]\n
+<li><a href="http://code.google.com/p/go/source/browse?repo=net"><code>code.google.com/p/go.net</code></a> [<a href="http://gopkgdoc.appspot.com/pkg/code.google.com/p/go.net">docs</a>]\n
+</ul>
+
 <h3 id="cmd"><a href="/ref/cmd">Command Documentation</a></h3>
 <p>
 The documentation for the Go tools.

コアとなるコードの解説

上記のdiffは、doc/reference.html ファイルに対する変更を示しています。

• @@ -14,6 +14,22 @@ は、変更がファイルの14行目から始まり、元の6行が変更後には22行になることを示しています。これは、新しいコンテンツが追加されたことを意味します。
• + で始まる行は、新たに追加された行です。

具体的には、既存の <p> タグ（Go標準ライブラリのドキュメントに関する説明）と <h3 id="cmd"> タグ（コマンドドキュメントの見出し）の間に、以下のHTMLコードが挿入されています。

1. <h4 id="subrepos">Sub-repositories</h4>: 「Sub-repositories」という新しいセクションの見出しを定義しています。id="subrepos" は、このセクションへの直接リンク（例: #subrepos）を可能にします。

2. <p>...</p>: サブリポジトリに関する説明文です。

   • These packages are part of the Go Project but outside the main Go tree.：サブリポジトリがGoプロジェクトの一部でありながら、メインのGoツリーとは独立していることを説明しています。
   • They are developed under looser <a href="/doc/go1compat.html">compatibility requirements</a> than the Go core.：Goコアよりも緩やかな互換性要件の下で開発されていることを明記し、その詳細が記述されている go1compat.html へのリンクを提供しています。
   • Install them with "<code><a href="/cmd/go/#Download_and_install_packages_and_dependencies">go get</a></code>".：go get コマンドを使用してインストールすることを推奨し、go コマンドのドキュメント内の関連セクションへのリンクを提供しています。

3. <ul>...</ul>: サブリポジトリのリストです。

   • 各 <li> 要素は、個々のサブリポジトリを表します。
   • <a> タグは、各サブリポジトリのソースコードブラウザ（http://code.google.com/p/go/source/browse?repo=...）へのリンクを提供しています。
   • <code> タグで囲まれたテキストは、Goのパッケージパス（例: code.google.com/p/go.codereview）を示しており、ユーザーがコピー＆ペーストしやすいように配慮されています。
   • [<a href="http://gopkgdoc.appspot.com/pkg/.../">docs</a>] の部分は、各サブリポジトリの gopkgdoc.appspot.com 上のドキュメントページへのリンクを提供しています。これは、当時のGoパッケージの自動生成ドキュメントサービスでした。

この変更により、Goの公式リファレンスページから、Goプロジェクトの重要なサブリポジトリへのアクセスが容易になり、ユーザーがGoエコシステム全体をより深く探索できるようになりました。

関連リンク

• Go CL 5752049: https://golang.org/cl/5752049 (Goのコードレビューシステムへのリンク)

参考にした情報源リンク

• GitHubコミットページ: https://github.com/golang/go/commit/cfe007e1b67f869ed6d9ef8f188c2627b2ca4e25
• Go 1 Compatibility Promise: https://go.dev/doc/go1compat (現在のGo公式ドキュメントの互換性ページ)
• Go Command Documentation: https://go.dev/cmd/go/ (現在のGo公式ドキュメントの go コマンドページ)
• Go Reference Documentation: https://go.dev/doc/reference (現在のGo公式ドキュメントのリファレンスページ)
• Go Sub-repositories (当時の情報に基づく): code.google.com/p/go.codereview, code.google.com/p/go.crypto, code.google.com/p/go.image, code.google.com/p/go.net (これらは当時のGoogle Code上のリポジトリであり、現在はGitHubなどに移行しています。)
• gopkgdoc.appspot.com (当時のGoパッケージドキュメントホスティングサービス)