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

このコミットは、Go 1リリースノートのドキュメント（doc/go1.htmlおよびそのテンプレートdoc/go1.tmpl）を更新し、Go言語のパッケージ階層の再編成と、マップからの要素削除の構文変更（delete組み込み関数の導入）を反映させるものです。具体的には、新しいパッケージパスを示すテーブルの追加と、関連するCSSスタイルの定義が含まれています。

コミット

commit 9d59c40eabae6ae1c4f11aa9227a9fd69156599a
Author: Rob Pike <r@golang.org>
Date:   Thu Dec 8 11:35:28 2011 -0800

    doc/go1: document rearranged package hierarchy
    Some exciting HTML and CSS here.

    R=remyoudompheng, rsc, r
    CC=golang-dev
    https://golang.org/cl/5460047

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

https://github.com/golang/go/commit/9d59c40eabae6ae1c4f11aa9227a9fd69156599a

元コミット内容

Go 1リリースノートのドキュメントにおいて、再編成されたパッケージ階層と、マップからの要素削除に関する変更を記述する。これには、HTMLとCSSの更新が含まれる。

変更の背景

Go 1は、Go言語にとって最初の安定版リリースであり、言語仕様と標準ライブラリに多くの重要な変更が導入されました。このコミットは、その中でも特にユーザーに大きな影響を与える以下の2つの変更点を、公式リリースノートに正確に反映させることを目的としています。

1. パッケージ階層の再編成: Go 1では、標準ライブラリのパッケージがより論理的かつ整理された構造に再配置されました。例えば、utf8やutf16がunicodeパッケージのサブディレクトリに移動するなど、関連する機能がグループ化されました。これにより、開発者が目的のパッケージを見つけやすくなり、ライブラリ全体の整合性が向上しました。この変更は既存のコードベースに影響を与えるため、リリースノートで明確に伝える必要がありました。
2. delete組み込み関数の導入: Go言語の初期バージョンでは、マップからの要素削除はdelete(m, key)のような特殊な構文で行われていました。しかし、この構文にはいくつかの問題があったため、Go 1ではより一貫性のある組み込み関数deleteが導入されました。この変更も既存のコードの修正を必要とするため、リリースノートでその新しい使用法と背景を説明することが不可欠でした。

これらの変更は、Go言語の安定性と使いやすさを向上させるための重要なステップであり、ユーザーがGo 1へスムーズに移行できるよう、詳細なドキュメント化が求められました。

前提知識の解説

Go言語のパッケージシステム

Go言語は、コードのモジュール化と再利用を促進するためにパッケージシステムを採用しています。各Goプログラムは1つ以上のパッケージで構成され、関連する機能がまとめられています。パッケージはファイルシステム上のディレクトリに対応し、importステートメントによって他のパッケージの機能を利用できます。Go 1以前は、パッケージの配置が必ずしも最適化されておらず、一部のパッケージはより適切なカテゴリに再編成される必要がありました。

Go 1リリース

Go 1は、2012年3月28日にリリースされたGo言語の最初のメジャー安定版リリースです。このリリースは、Go言語の将来のバージョンとの互換性を保証する「Go 1 Compatibility Promise」の基盤を築きました。Go 1では、言語仕様、標準ライブラリ、ツールチェインに多くの変更が加えられ、Go言語が実用的なプログラミング言語として広く採用されるための重要なマイルストーンとなりました。

gofixツール

gofixは、Go言語のツールチェインに含まれるユーティリティで、Go言語のバージョンアップに伴うAPIの変更や構文の変更に、既存のGoソースコードを自動的に適応させるために使用されます。Go 1のような大規模な変更があった場合、gofixは開発者が手動でコードを修正する手間を大幅に削減し、スムーズな移行を支援します。このコミットの変更点の一部（特にパッケージ名の変更）は、gofixによって自動的に処理されることが期待されていました。

HTMLとCSS

このコミットは、Go 1リリースノートのWebページを更新するため、HTML（HyperText Markup Language）とCSS（Cascading Style Sheets）の知識が関連します。HTMLはWebページの構造を定義し、CSSはWebページの見た目（スタイル、レイアウトなど）を定義します。このコミットでは、新しいコンテンツ（パッケージ移動のテーブル）をHTMLに追加し、そのテーブルの表示を整形するためにCSSが追加されています。

技術的詳細

このコミットは、主にGo 1リリースノートのドキュメント（doc/go1.htmlおよびdoc/go1.tmpl）に対するHTMLとCSSの変更を含んでいます。

1. HTML構造の変更 (doc/go1.html, doc/go1.tmpl):

   • 自動生成コメントの追加: <!-- DO NOT EDIT: created by tmpltohtml go1.tmpl -->というコメントが追加され、go1.htmlがgo1.tmplから自動生成されることを明示しています。これにより、手動での編集を避け、テンプレートを介した一貫した更新を促します。
   • セクションIDの簡素化: 既存のh3タグのid属性がより短く、簡潔な名前に変更されています（例: composite_literalsからliterals、map_deletionからdelete）。これは、URLのアンカーリンクをより読みやすく、覚えやすくするための改善と考えられます。
   • delete関数の説明の更新: マップからの要素削除に関する説明が更新され、Go 1で導入された新しい組み込み関数deleteの使用法が明確に記述されています。以前の構文が廃止されたことが強調されています。
   • パッケージ階層のテーブル追加: 最も重要な変更点として、<h3 id="hierarchy">The package hierarchy</h3>セクションの下に、新しいHTMLテーブルが追加されています。このテーブルは、Go 1で移動したパッケージの「Old path」（古いパス）と「New path」（新しいパス）を一覧で示しています。
     • encoding関連: asn1, csv, gob, json, xmlがencoding/以下に移動。
     • html/template: exp/template/htmlから移動。
     • math関連: big, cmath（math/cmplxに改名）、randがmath/以下に移動。
     • net関連: http, http/cgi, http/fcgi, http/httptest, http/pprof, mail, rpc, rpc/jsonrpc, smtp, urlがnet/以下に移動。
     • os/exec: execから移動。
     • text関連: scanner, tabwriter, template, template/parseがtext/以下に移動。
     • unicode関連: utf8, utf16がunicode/以下に移動。
   • パッケージ名の変更に関する注意: cmathがcmplxに、exp/template/htmlがtemplateにパッケージ名自体も変更されたことが明記されています。
   • gofixによる更新の言及: gofixツールが標準リポジトリ内に残るパッケージのインポートとパッケージ名の変更を自動的に更新することが説明されています。標準リポジトリから削除されたパッケージについては手動での編集が必要であることも示唆されています。
   • TODOコメント: 削除されたパッケージやサブリポジトリに移動したパッケージに関する警告をgofixがどのように扱うかについてのTODOコメントが残されています。
   • 削除されたパッケージとサブリポジトリに移動したパッケージのリスト: コメントアウトされたセクションで、Go 1で削除された、またはサブリポジトリに移動したパッケージのリストが示されています。

2. CSSスタイルの追加 (doc/all.css):

   • 新しいCSSルール.codetable tdが追加されています。これは、Go 1リリースノートに追加されたパッケージ階層のテーブル（class="codetable"を持つテーブル）内のセル（td）に適用されます。
   • font-family: monospace;とfont-size: 120%;が設定されており、テーブル内のコードパスが等幅フォントで、かつ少し大きめのサイズで表示されるように整形されています。これにより、コードパスの視認性が向上し、ドキュメントの可読性が高まります。

これらの変更は、Go 1の重要な変更点をユーザーに明確に伝え、新しいパッケージ構造とAPIの変更にスムーズに適応できるようにするためのドキュメンテーションの改善です。

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

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

1. doc/all.css:

   /* Table of code entries; used by go1.html */
   .codetable td {
      font-family: monospace;
      font-size: 120%;
   }
   

   このCSSルールは、Go 1リリースノートに追加されるパッケージ移動のテーブルの表示スタイルを定義しています。

2. doc/go1.html および doc/go1.tmpl: これらのファイルはほぼ同じ変更を含んでおり、特に以下のセクションが重要です。

   • マップからの要素削除に関する説明の更新:

     <p>
     -This syntax had a number of minor problems and is being replaced.
     -As of Go 1, that syntax is gone and in its place is a new built-in
     +In Go 1, that syntax has gone; instead there is a new built-in
     function, <code>delete</code>.  The call
     </p>
     

     delete組み込み関数の導入を説明するテキストが変更されています。

   • パッケージ階層のテーブルの追加: <h3 id="hierarchy">The package hierarchy</h3>の下に、以下の構造を持つテーブルが追加されています。

     <table class="codetable" frame="border" summary="Moved packages">
     <colgroup align="left" width="60%"></colgroup>
     <colgroup align="left" width="40%"></colgroup>
     <tr>
     <th align="left">Old path</th>
     <th align="left">New path</th>
     </tr>
     <tr><td>asn1 <td>encoding/asn1
     <tr><td>csv</td> <td>encoding/csv</td></tr>
     ... (多数のパッケージ移動エントリ) ...
     <tr><td>utf8</td> <td>unicode/utf8</td></tr>
     <tr><td>utf16</td> <td>unicode/utf16</td></tr>
     </table>
     

     このテーブルは、Go 1で移動した主要なパッケージの古いパスと新しいパスを一覧で示しています。

コアとなるコードの解説

doc/all.css の変更

doc/all.cssに追加されたCSSルール.codetable tdは、Go 1リリースノートのWebページに新しく導入されたパッケージ移動のテーブルの視覚的な表現を向上させるために設計されています。

• font-family: monospace;: テーブル内のセル（<td>）に表示されるテキスト（主にパッケージパス）を等幅フォントで表示するように指定します。これにより、コードやパスがより読みやすく、整形された形で表示されます。
• font-size: 120%;: テキストのフォントサイズを通常の120%に拡大します。これにより、特に長いパッケージパスや多数のエントリがある場合でも、視認性が向上し、ユーザーが情報を素早く把握できるようになります。

このCSSの追加は、単なる見た目の変更ではなく、技術的な情報を効果的に伝えるためのユーザビリティの改善に貢献しています。

doc/go1.html および doc/go1.tmpl の変更

これらのファイルはGo 1リリースノートのコンテンツを定義しており、変更は主に以下の2つの重要な側面を反映しています。

1. delete組み込み関数の説明: Go 1では、マップからの要素削除の構文が変更され、新しい組み込み関数deleteが導入されました。この変更は、Go言語のAPIの一貫性を高めるためのものでした。コミットでは、リリースノートの該当セクションのテキストが更新され、古い構文が廃止され、新しいdelete関数を使用する必要があることが明確に説明されています。これにより、既存のGoコードをGo 1に移行する開発者が、この変更に適切に対応できるようになります。

2. パッケージ階層の再編成のドキュメント化: Go 1の標準ライブラリでは、パッケージがより論理的な構造に再編成されました。例えば、encoding/jsonやnet/httpのように、関連する機能がサブディレクトリにグループ化されました。この変更は、ライブラリの発見可能性と整理を改善することを目的としています。 コミットでは、この大規模な変更をユーザーに伝えるために、新しいHTMLテーブルが導入されました。このテーブルは、古いパッケージパスと新しいパッケージパスを対比させて一覧表示することで、開発者が自分のコードベースで必要なインポートパスの変更を容易に特定できるようにします。 また、gofixツールがこれらのインポートパスの変更の一部を自動的に処理できることにも言及されており、移行プロセスをさらに簡素化する情報が提供されています。

これらのHTMLの変更は、Go 1のリリースに伴う重要な言語およびライブラリの変更を、明確かつ包括的な方法でユーザーに伝えるための中心的な役割を果たしています。

関連リンク

• Go Change List: https://golang.org/cl/5460047

参考にした情報源リンク

• Go 1 Release Notes: https://go.dev/doc/go1 (Web検索結果より)