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

このコミットは、Go言語プロジェクトへの貢献方法を説明するドキュメントファイル doc/contribute.html に対する複数の修正を含んでいます。具体的には、Windows環境でのビルドスクリプトの指示、テスト実行時の期待される出力の修正、2段階認証を使用している場合のアプリケーション固有パスワードに関する注意喚起、および変更リスト（CL）の編集方法に関する説明の追加が行われています。

コミット

このコミットは、Go言語プロジェクトへの貢献ガイドラインを記述した doc/contribute.html ファイルの正確性とユーザビリティを向上させることを目的としています。主な変更点は以下の通りです。

Windowsユーザー向けに、ビルドスクリプトとして all.bat を使用するよう明記。
all.bash 実行後の期待されるテスト出力メッセージを「ALL TESTS PASSED」に修正。
2段階認証を有効にしているユーザーが、アプリケーション固有のパスワードを使用する必要があることを追記。
変更リスト（CL）に含まれるファイルを編集する際に、hg change NNNN コマンドに加えて hg file コマンドを使用できることを説明。

これらの修正により、Goプロジェクトへの貢献プロセスがより明確になり、特にWindowsユーザーや2段階認証を利用しているユーザーにとっての障壁が低減されます。

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

https://github.com/golang/go/commit/4c473c02e13f2429c7776cc6585af420cd248502

元コミット内容

commit 4c473c02e13f2429c7776cc6585af420cd248502
Author: Shenghou Ma <minux.ma@gmail.com>
Date:   Thu Oct 11 23:33:57 2012 +0800

    doc/contribute.html: assorted fixes
    0. windows uses all.bat instead of ./all.bash
    1. correct expected all.bash output
    2. mention you need to use an application specific password
    if you're using 2-step verification
    3. note you can edit files included in CL by 'hg change NNNN'
    or 'hg file'
    
    R=golang-dev, adg, r
    CC=golang-dev
    https://golang.org/cl/6615060

変更の背景

このコミットが行われた背景には、Go言語プロジェクトへの貢献プロセスをよりスムーズにし、新規貢献者が直面する可能性のある一般的な問題を解消するという目的があります。

プラットフォーム間の差異への対応: Goプロジェクトはクロスプラットフォームで開発されており、Windowsユーザーも多く存在します。しかし、ドキュメントがUnix/Linux環境を前提とした all.bash のみを参照していたため、Windowsユーザーがビルドスクリプトで混乱する可能性がありました。これを解消するため、all.bat の使用を明記する必要がありました。
テスト出力の正確性: 開発環境の進化やテストスイートの変更に伴い、all.bash 実行後の期待される出力メッセージが古くなっていた可能性があります。正確なメッセージを記載することで、ユーザーがテストの成功を正しく判断できるようにする必要がありました。
セキュリティと利便性の両立: 2段階認証はアカウントのセキュリティを大幅に向上させますが、従来のパスワード入力では認証が完了しない場合があります。特に、自動化されたツールや特定のアプリケーションからアクセスする際には、アプリケーション固有のパスワードが必要となることが一般的です。Goプロジェクトへの貢献プロセスでこのような認証が必要となる場面があるため、事前にその情報を提供することで、ユーザーが認証でつまずくことを防ぐ目的がありました。
変更リスト（CL）管理の柔軟性向上: GoプロジェクトではMercurial（Hg）とGerritベースのコードレビューシステムが使用されていました。貢献者がCLを作成した後、そのCLに含まれるファイルを変更したり、追加・削除したりする際に、より柔軟なコマンドオプションを提供することで、ワークフローを改善する必要がありました。特に hg file コマンドは、CLのファイル構成を細かく調整する際に有用です。

これらの変更は、Goプロジェクトのドキュメントが常に最新かつ正確であり、多様な環境やセキュリティ設定を持つ貢献者にとって使いやすいものであることを保証するための継続的な取り組みの一環です。

前提知識の解説

このコミットの理解を深めるために、以下の前提知識を解説します。

1. Go言語のビルドシステムとテストスクリプト (`all.bash`, `all.bat`)

Go言語のソースコードをビルドし、テストを実行するためのスクリプトです。

all.bash: Unix/Linux/macOS環境で使用されるシェルスクリプトです。Goのソースツリーのルートにある src ディレクトリ内で実行され、Goツールチェインのビルド、標準ライブラリのコンパイル、そして全てのテストの実行を行います。Goプロジェクトへの貢献者は、変更をコミットする前にこのスクリプトを実行し、既存の機能が壊れていないことを確認することが推奨されます。
all.bat: Windows環境で使用されるバッチファイルです。all.bash と同様の目的で、Goツールチェインのビルドとテスト実行を行います。Windowsのコマンドプロンプト環境に合わせて記述されています。

これらのスクリプトは、Go開発者が自身の変更がGoエコシステム全体に悪影響を与えないことを確認するための重要なツールです。

2. 2段階認証 (Two-step verification) とアプリケーション固有パスワード (Application-specific password)

2段階認証: オンラインアカウントのセキュリティを強化するための認証方法です。通常のパスワードに加えて、スマートフォンに送信されるコードや生体認証など、別の認証要素を要求します。これにより、パスワードが漏洩した場合でも、不正アクセスを防ぐことができます。
アプリケーション固有パスワード: 2段階認証が有効になっているアカウントで、特定のアプリケーション（例: メールクライアント、Gitクライアント、APIアクセスなど）からアクセスする際に使用する、一度だけ生成される特別なパスワードです。通常のパスワードとは異なり、このパスワードは特定のアプリケーションにのみ関連付けられ、アカウントのセキュリティを維持しつつ、2段階認証に対応していないアプリケーションからのアクセスを可能にします。Googleアカウントなど、多くのサービスで提供されています。Goプロジェクトへの貢献では、Gerritなどのコードレビューシステムへのアクセス時に必要となる場合があります。

3. Mercurial (Hg) と変更リスト (Change List: CL)

Goプロジェクトは、かつてバージョン管理システムとしてMercurial（略称: Hg）を使用していました。Gitが主流となる以前は、多くのオープンソースプロジェクトで利用されていました。

Mercurial (Hg): 分散型バージョン管理システム（DVCS）の一つで、Gitと同様にリポジトリのクローン、コミット、ブランチ、マージなどの機能を提供します。Goプロジェクトでは、MercurialとGerrit（コードレビューシステム）を組み合わせて開発ワークフローを構築していました。
変更リスト (Change List: CL): Gerritなどのコードレビューシステムにおいて、レビューのために提出される一連の変更（通常は1つまたは複数のコミット）を指します。貢献者は、自身の変更をCLとして提出し、他の開発者からのレビューと承認を得てから、メインのコードベースにマージされます。

4. Mercurialコマンド (`hg change`, `hg file`)

Mercurialには、CLを管理するための特定のコマンドがあります。

hg change NNNN: Gerritに提出されたCLのID（NNNN）を指定して、そのCLの変更内容や説明を編集するためのコマンドです。このコマンドを実行すると、エディタが開き、CLのコミットメッセージや含まれるファイルのリストを修正できます。
hg file NNNN [somefile]: 特定のCL（NNNN）にファイルを追加したり、削除したりするためのコマンドです。
- hg file NNNN somefile: somefile をCL NNNN に追加します。
- hg file -d NNNN somefile: somefile をCL NNNN から削除します。これは、CLのスコープを調整したり、レビュー中にファイルの追加・削除が必要になった場合に非常に便利です。

これらの知識は、Goプロジェクトの過去の貢献ワークフローと、このコミットが解決しようとしている問題点を理解する上で不可欠です。

技術的詳細

このコミットは、doc/contribute.html ファイル内の具体的な指示を更新し、Goプロジェクトへの貢献プロセスをより正確かつ包括的にするためのものです。各変更点について技術的な詳細を掘り下げます。

1. Windows環境でのビルドスクリプトの明記

変更前:
```
<pre>
cd $GOROOT/src
./all.bash
</pre>
```
この記述は、Unix/Linux/macOS環境を前提としており、Windowsユーザーが all.bash を直接実行しようとするとエラーになるか、期待通りに動作しませんでした。Windowsではシェルスクリプトではなく、バッチファイルが一般的に使用されます。
変更後:
```
<pre>
cd $GOROOT/src
./all.bash # On Windows, run all.bat
</pre>
```
この変更により、Windowsユーザーは all.bat を実行する必要があることが明確に示されました。これは、クロスプラットフォーム開発におけるドキュメントの重要性を示しており、特定のOSに依存しない指示を提供することで、より広範な貢献者ベースに対応するための配慮です。技術的には、all.bash と all.bat はそれぞれ異なるスクリプト言語（BashとBatch Script）で書かれていますが、Goプロジェクトのビルドとテストという同じ目的を達成します。

2. `all.bash` 実行後の期待される出力の修正

変更前:
```

The final line printed by <code>make all</code> should be of the form:


<pre>
N known bugs; 0 unexpected bugs
</pre>


The value of N varies over time, but the line must
say &ldquo;<code>0 unexpected bugs</code>&rdquo; and must not
add &ldquo;<code>test output differs</code>.&rdquo;

```
この記述は、Goのビルドシステムが make all を使用していた時期の古い情報であり、テスト結果の表示形式も現在とは異なっていました。特に「N known bugs; 0 unexpected bugs」という形式は、Goのテストフレームワークの進化に伴い使われなくなっていました。
変更後:
```

After running for a while, the command should print "<code>ALL TESTS PASSED</code>".

```
この修正は、Goのテストスクリプトが成功した場合に表示される標準的なメッセージ「ALL TESTS PASSED」に更新されました。これにより、貢献者はテストが正常に完了したことをより直感的に確認できるようになりました。これは、ドキュメントが実際のシステムの状態と同期していることの重要性を示しています。

3. 2段階認証とアプリケーション固有パスワードに関する注意喚起

変更前: 2段階認証に関する記述は存在しませんでした。
変更後:
```

If you've enabled the two-step verification feature, don't forget to generate an
application-specific password and use that when prompted for a password.

```
この追加は、セキュリティ意識の高まりと、多くのユーザーがGoogleアカウントなどで2段階認証を有効にしている現状に対応したものです。Goプロジェクトへの貢献プロセスでは、Gerritなどのコードレビューシステムへの認証にGoogleアカウントを使用することが一般的でした。2段階認証が有効な場合、通常のGoogleアカウントのパスワードでは認証が失敗するため、事前にアプリケーション固有パスワードの生成と使用を促すことで、ユーザーが認証プロセスでつまずくことを防ぎます。これは、ユーザーエクスペリエンスの向上と、セキュリティベストプラクティスへの対応の両方を考慮した変更です。

4. 変更リスト（CL）の編集方法に関する説明の追加

変更前:
```

If you need to re-edit the change description,
run <code>hg change 99999</code>.

```
この記述は、CLのコミットメッセージ（変更説明）を編集する方法のみを説明していました。しかし、CLに含まれるファイルを変更したり、追加・削除したりするニーズも頻繁に発生します。
変更後:
```

If you need to re-edit the change description, or change the files included in the CL,
run <code>hg change 99999</code>. Alternatively, you can use <code>hg file 99999 somefile</code>
to add <code>somefile</code> to CL 99999, and use <code>hg file -d 99999 somefile</code> to remove
<code>somefile</code> from the CL.

```
この変更により、CLのコミットメッセージだけでなく、CLに含まれるファイルの追加・削除も可能であることが明記されました。特に hg file コマンドの導入は、貢献者がCLのスコープをより柔軟に管理できるようにするための重要な改善です。これにより、レビュー中にファイルの追加や削除が必要になった場合でも、新しいCLを作成し直すことなく、既存のCLを修正できるようになり、ワークフローの効率が向上します。これは、MercurialとGerritを組み合わせた当時のGoのコードレビューワークフローにおける、実践的なヒントを提供しています。

これらの技術的詳細は、単なるドキュメントの修正ではなく、Goプロジェクトの当時の開発環境、セキュリティ要件、および貢献者のワークフローに対する深い理解に基づいていることを示しています。

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

diff --git a/doc/contribute.html b/doc/contribute.html
index 8320657904..683c387373 100644
--- a/doc/contribute.html
+++ b/doc/contribute.html
@@ -46,24 +46,13 @@ tree to make sure the changes don't break other packages or programs:
 
 <pre>
 cd $GOROOT/src
-./all.bash
+./all.bash    # On Windows, run all.bat
 </pre>
 
 <p>
-The final line printed by <code>make all</code> should be of the form:
+After running for a while, the command should print "<code>ALL TESTS PASSED</code>".
 </p>
 
-<pre>
-<i>N</i> known bugs; 0 unexpected bugs
-</pre>
-
-<p>
-The value of <i>N</i> varies over time, but the line must
-say &ldquo;<code>0 unexpected bugs</code>&rdquo; and must not
-add &ldquo;<code>test output differs</code>.&rdquo;
-</p>
-
-
 <h2 id="Code_review">Code review</h2>
 
 <p>
@@ -133,6 +122,8 @@ will be recorded in the <a href="http://code.google.com/p/go/source/list">Mercur
 and in the <a href="/CONTRIBUTORS"><code>CONTRIBUTORS</code></a> file.
 You can <a href="https://www.google.com/accounts/NewAccount">create a Google Account</a>
 associated with any address where you receive email.
+If you've enabled the two-step verification feature, don't forget to generate an
+application-specific password and use that when prompted for a password.
 </p>
 
 <pre>
@@ -285,8 +276,10 @@ CL created: http://codereview.appspot.com/99999
 </pre>
 
 <p>
-If you need to re-edit the change description,
-run <code>hg change 99999</code>.
+If you need to re-edit the change description, or change the files included in the CL,
+run <code>hg change 99999</code>. Alternatively, you can use <code>hg file 99999 somefile</code>
+to add <code>somefile</code> to CL 99999, and use <code>hg file -d 99999 somefile</code> to remove
+<code>somefile</code> from the CL.
 </p>
 
 <p>

コアとなるコードの解説

このコミットは、doc/contribute.html ファイル内のHTMLコンテンツを直接修正しています。以下に、各変更ブロックの具体的な解説を示します。

1. Windows向けビルドスクリプトの指示追加

@@ -46,24 +46,13 @@ tree to make sure the changes don't break other packages or programs:
 
 <pre>
 cd $GOROOT/src
-./all.bash
+./all.bash    # On Windows, run all.bat
 </pre>

変更内容: all.bash の行に # On Windows, run all.bat というコメントが追加されました。
解説: これは、WindowsユーザーがGoのソースコードをビルドしテストを実行する際に、all.bash ではなく all.bat を使用する必要があることを明確にするための修正です。これにより、異なるOS環境で作業する貢献者が、適切なスクリプトを選択できるようになります。

2. テスト成功時の出力メッセージの修正

 <p>
-The final line printed by <code>make all</code> should be of the form:
+After running for a while, the command should print "<code>ALL TESTS PASSED</code>".
 </p>
 
-<pre>
-<i>N</i> known bugs; 0 unexpected bugs
-</pre>
-
-<p>
-The value of <i>N</i> varies over time, but the line must
-say &ldquo;<code>0 unexpected bugs</code>&rdquo; and must not
-add &ldquo;<code>test output differs</code>.&rdquo;
-</p>
-
-

変更内容:
- The final line printed by <code>make all</code> should be of the form: という段落と、それに続く <pre> タグ内の古いテスト出力形式 (N known bugs; 0 unexpected bugs) およびその説明が削除されました。
- 代わりに、After running for a while, the command should print "<code>ALL TESTS PASSED</code>". という新しい段落が追加されました。
解説: この変更は、Goのビルドおよびテストシステムが進化し、テスト成功時の標準的な出力メッセージが「ALL TESTS PASSED」になったことを反映しています。古い make all の参照とバグカウントの形式はもはや正確ではなかったため、削除され、現在のGoのテストフレームワークに合わせた簡潔で明確な指示に置き換えられました。

3. 2段階認証とアプリケーション固有パスワードに関する注意喚起の追加

@@ -133,6 +122,8 @@ will be recorded in the <a href="http://code.google.com/p/go/source/list">Mercur
 and in the <a href="/CONTRIBUTORS"><code>CONTRIBUTORS</code></a> file.
 You can <a href="https://www.google.com/accounts/NewAccount">create a Google Account</a>
 associated with any address where you receive email.
+If you've enabled the two-step verification feature, don't forget to generate an
+application-specific password and use that when prompted for a password.
 </p>

変更内容: Googleアカウントの作成に関する既存の段落に、2段階認証を有効にしている場合のアプリケーション固有パスワードの使用を促す新しい文が追加されました。
解説: Goプロジェクトへの貢献では、Gerritなどのコードレビューシステムへの認証にGoogleアカウントが使用されることがありました。2段階認証が有効な場合、通常のパスワードでは認証が失敗するため、ユーザーが事前にアプリケーション固有パスワードを生成して使用する必要があることを明記することで、認証プロセスでの混乱を防ぎ、スムーズな貢献を促します。

4. 変更リスト（CL）の編集方法に関する詳細な説明の追加

@@ -285,8 +276,10 @@ CL created: http://codereview.appspot.com/99999
 </pre>
 
 <p>
-If you need to re-edit the change description,
-run <code>hg change 99999</code>.
+If you need to re-edit the change description, or change the files included in the CL,
+run <code>hg change 99999</code>. Alternatively, you can use <code>hg file 99999 somefile</code>
+to add <code>somefile</code> to CL 99999, and use <code>hg file -d 99999 somefile</code> to remove
+<code>somefile</code> from the CL.
 </p>

変更内容:
- 既存の If you need to re-edit the change description, run <code>hg change 99999</code>. という文が拡張されました。
- or change the files included in the CL, という句が追加され、hg file コマンドを使ったファイルの追加・削除方法が具体的に説明されました。
解説: この修正は、貢献者がMercurialとGerritを使用して変更リスト（CL）を管理する際の柔軟性を高めるためのものです。以前はCLのコミットメッセージの編集方法しか説明されていませんでしたが、この変更により、CLに含まれるファイルの追加や削除も hg file コマンドを使って行えることが明確になりました。これにより、レビュー中にCLのスコープを変更する必要が生じた場合でも、より効率的に対応できるようになります。

これらの変更は、Goプロジェクトの貢献ドキュメントを最新の状態に保ち、貢献者が直面する可能性のある一般的な問題を事前に解決することで、貢献プロセス全体のユーザビリティと効率を向上させることを目的としています。

参考にした情報源リンク

Mercurial 公式サイト: https://www.mercurial-scm.org/
Gerrit Code Review: https://www.gerritcodereview.com/
Google アカウントの 2 段階認証プロセス: https://support.google.com/accounts/answer/185834?hl=ja
アプリケーションパスワードでログインする: https://support.google.com/accounts/answer/185833?hl=ja
Go言語の公式ドキュメント: (当時の doc/contribute.html の内容を理解するための一般的な情報源)```markdown