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

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

このコミットは、Goプロジェクトの貢献ガイドドキュメント（doc/contribute.html）に対する変更です。具体的には、Mercurial (hg) を使用した当時のワークフローにおいて、変更をアップロードした後にレビュー担当者へ通知するために hg mail コマンドを実行する必要があることを明示的に追記しています。

コミット

  • コミットハッシュ: c64469f8e8d035207e629d925b3124dce068e907
  • Author: Russ Cox rsc@golang.org
  • Date: Fri Jan 18 14:08:42 2013 -0500
  • コミットメッセージ: 
    doc/contribute.html: mention hg mail during hg change discussion

People keep not reading all the way to the bottom of the doc
and not running hg mail.

R=golang-dev, minux.ma
CC=golang-dev
https://golang.org/cl/7137057

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

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

元コミット内容

doc/contribute.html: mention hg mail during hg change discussion

People keep not reading all the way to the bottom of the doc
and not running hg mail.

R=golang-dev, minux.ma
CC=golang-dev
https://golang.org/cl/7137057

変更の背景

このコミットが行われた2013年当時、Goプロジェクトはバージョン管理システムとしてMercurial (hg) を使用しており、コードレビュープロセスには hg mail コマンドが不可欠でした。コミットメッセージによると、多くの貢献者がドキュメントの最後まで読み進めず、hg mail を実行し忘れるという問題が発生していました。

hg mail は、変更セット（パッチ）をコードレビューサーバーにアップロードした後、その変更がレビュー待ちであることを関係者に通知するための重要なステップでした。この通知が行われないと、アップロードされた変更がレビュー担当者によって見過ごされ、レビュープロセスが滞る原因となっていました。

この問題を解決するため、ドキュメントのより目立つ位置に hg mail の重要性を強調する記述を追加することで、貢献者がこのステップを見落とさないように促すことが目的でした。

前提知識の解説

Mercurial (hg)

Mercurial（通称 hg）は、Gitと同様の分散型バージョン管理システム（DVCS）です。Goプロジェクトは初期にMercurialを使用していましたが、後にGitに移行しました。Mercurialは、リポジトリのクローン、変更のコミット、ブランチの管理など、Gitと類似した機能を提供します。

hg mail コマンド

GoプロジェクトのMercurialベースのワークフローでは、変更を提案する際に以下の手順を踏んでいました。

  1. 変更の作成: コードを修正し、ローカルリポジトリに変更をコミットします。
  2. 変更セットのアップロード: hg upload や hg push のようなコマンド（またはGoプロジェクト独自のツール）を使用して、変更セットをコードレビューシステム（当時のGoプロジェクトではGerritのようなシステムが使われていた可能性がありますが、このコミットの文脈では「コードレビューサーバー」と表現されています）にアップロードします。
  3. レビュー担当者への通知: このステップが hg mail の役割でした。 変更セットがサーバーにアップロードされただけでは、レビュー担当者はその存在を知りません。hg mail コマンドを実行することで、アップロードされた変更セットへのリンクや概要を含むメールが、指定されたレビュー担当者やメーリングリスト（例: golang-dev）に送信され、レビューを促す通知が行われました。

この通知プロセスは、今日のGitとGerritを組み合わせたワークフローにおけるGerritの自動通知機能に相当します。Gerritでは変更がアップロードされると自動的にレビュー担当者に通知が行われますが、当時のMercurialベースのワークフローでは、この通知を手動でトリガーする必要があったのです。

Goプロジェクトの貢献ワークフローの変遷

Goプロジェクトの貢献ワークフローは、このコミットが行われた2013年以降、大きく進化しています。現在では、バージョン管理システムはGitに移行し、コードレビューシステムはGerritが中心となっています。

  • 現在のワークフロー:
    1. Gitでリポジトリをクローンし、変更を加える。
    2. git commit で変更をコミットする。
    3. git-codereview ツール（Goプロジェクトが提供するGerrit連携ツール）を使用して、変更をGerritにアップロードする。
    4. Gerritが自動的にレビュー担当者に通知し、ウェブインターフェース上でレビューと議論が行われる。

このコミットは、Goプロジェクトの歴史的な貢献プロセスのスナップショットを示しており、当時の開発者が直面していた課題と、それを解決するためのドキュメント改善の取り組みを反映しています。

技術的詳細

このコミットは、doc/contribute.html というHTMLドキュメントに新しいパラグラフを追加するものです。追加された内容は、変更セットをコードレビューサーバーにアップロードしただけでは通知が行われないこと、そして hg mail を実行して通知する必要があることを明確に伝えています。

具体的には、既存の <p> タグの後に新しい <p> タグが挿入されています。

<p>
Creating the change uploads a copy of the diff to the code review server, but it does not
notify anyone about it. To do that, you need to run <code>hg mail</code> (see below).
</p>

この変更は、ドキュメントの「変更の作成とアップロード」に関するセクションの直後に配置されており、貢献者が変更をアップロードした後に次に何をすべきかをすぐに理解できるように意図されています。<code>hg mail</code> のようにコードスニペットを強調し、「(see below)」と追記することで、さらに詳細な情報がドキュメントの後半にあることを示唆しています。

このシンプルなテキストの追加は、ユーザーエクスペリエンスの改善と、貢献プロセスの円滑化を目的としたものです。技術的なコード変更ではなく、ドキュメンテーションの改善を通じて、ヒューマンエラーを減らし、プロジェクトへの貢献をよりスムーズにするための典型的なアプローチと言えます。

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

diff --git a/doc/contribute.html b/doc/contribute.html
index b9e268a99f..494f05880b 100644
--- a/doc/contribute.html
+++ b/doc/contribute.html
@@ -289,6 +289,11 @@ to add <code>somefile</code> to CL 99999, and use <code>hg file -d 99999 somefil
 <code>somefile</code> from the CL.
 </p>
 
+<p>
+Creating the change uploads a copy of the diff to the code review server, but it does not
+notify anyone about it. To do that, you need to run <code>hg mail</code> (see below).
+</p>
+
 <p>
 You can see a list of your pending changes by running <code>hg pending</code> (<code>hg p</code> for short).
 </p>

コアとなるコードの解説

上記の差分は、doc/contribute.html ファイルに5行の追加が行われたことを示しています。

追加されたHTMLスニペットは以下の通りです。

<p>
Creating the change uploads a copy of the diff to the code review server, but it does not
notify anyone about it. To do that, you need to run <code>hg mail</code> (see below).
</p>

このパラグラフは、以下の重要な情報を貢献者に伝えています。

  1. 変更のアップロードだけでは不十分: 「Creating the change uploads a copy of the diff to the code review server, but it does not notify anyone about it.」（変更を作成し、差分をコードレビューサーバーにアップロードしても、誰もそれについて通知されません。） これは、当時のワークフローにおける一般的な誤解を解消するためのものです。多くのユーザーは、変更をアップロードすれば自動的にレビュープロセスが開始されると考えていた可能性があります。
  2. hg mail の必要性: 「To do that, you need to run hg mail (see below).」（そのためには、hg mail を実行する必要があります（以下参照）。） この文は、通知を行うための具体的なアクション（hg mail の実行）を明確に指示しています。また、「(see below)」という指示は、hg mail コマンドの詳細な説明がドキュメントのさらに下部に存在することを示唆しており、ユーザーがより詳しい情報を探す手助けとなります。

この変更は、ドキュメントの可読性と指示の明確さを向上させ、貢献者がGoプロジェクトのワークフローをより正確に理解し、スムーズに貢献できるようにすることを目的としています。

関連リンク

  • 現在のGoプロジェクトへの貢献ガイド: https://go.dev/doc/contribute (このコミット当時のMercurialベースのワークフローとは異なりますが、現在の公式な貢献方法です。)

参考にした情報源リンク