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

このコミットは、Go言語プロジェクトのコードレビューツール (lib/codereview/codereview.py) におけるユーザビリティの改善を目的としています。具体的には、hg mail コマンドや hg submit コマンドを、変更対象のファイル名を指定せずに実行した場合に表示されるエラーメッセージをより分かりやすくし、既存の変更リスト（CL）を使用するための適切なコマンド引数（CL番号）を提案するように変更しています。これにより、ユーザーが次に取るべきアクションを明確にガイドし、作業の効率化を図っています。

コミット

commit c3d881b3619f265571014a52dbb50abea515a96c
Author: Russ Cox <rsc@golang.org>
Date:   Tue Dec 11 13:36:55 2012 -0500

    lib/codereview: suggest argument to hg mail / hg submit

    R=golang-dev, iant
    CC=golang-dev
    https://golang.org/cl/6924050

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

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

元コミット内容

lib/codereview: hg mail および hg submit コマンドへの引数を提案する。

変更の背景

Go言語プロジェクトでは、Mercurial (hg) をバージョン管理システムとして使用し、独自のコードレビューツール (codereview.py) を利用していました。このツールには、変更をレビューのために送信する hg mail コマンドと、レビューが承認された変更をリポジトリにコミットする hg submit コマンドがあります。

これらのコマンドは、通常、特定の変更リスト（CL）番号を指定して実行されます。しかし、ユーザーがこれらのコマンドを、変更対象のファイル名を指定せずに、かつCL番号も指定せずに実行した場合、ツールは「no files changed」（変更されたファイルがありません）という一般的なエラーメッセージを返していました。このメッセージは、ユーザーが既存のCLを操作しようとしている場合に、次に何をすべきかについての具体的な指示を欠いていました。

このコミットの背景には、ユーザーがこのような状況に遭遇した際に、より適切なガイダンスを提供し、既存のCLを操作するための正しいコマンド引数（CL番号）を促すことで、ユーザーエクスペリエンスを向上させるという目的があります。これにより、ユーザーはエラーメッセージから直接、問題解決のための具体的なヒントを得られるようになります。

前提知識の解説

このコミットを理解するためには、以下の技術的背景知識が必要です。

1. Mercurial (hg):

   • Mercurialは、Gitと同様の分散型バージョン管理システム（DVCS）です。Go言語プロジェクトは、初期にはMercurialを使用してコードを管理していました。Gitとは異なるコマンド体系を持ちますが、基本的な概念（リポジトリ、コミット、ブランチ、マージなど）は共通しています。
   • hg mail: Goプロジェクトのコードレビュープロセスにおいて、変更をレビューのために送信するために使用されるコマンドです。これは、変更をメール形式でレビューシステムにアップロードする役割を担っていました。
   • hg submit: レビューが承認された変更を、最終的にメインリポジトリにコミットするために使用されるコマンドです。

2. Go言語のコードレビュープロセスと codereview.py:

   • Go言語プロジェクトは、Googleの内部ツールにインスパイアされた独自のコードレビューシステムを使用していました。このシステムは、Mercurialリポジトリと連携し、変更の提案、レビュー、承認、そして最終的なコミットを管理します。
   • codereview.py: このPythonスクリプトは、Goプロジェクトのコードレビューシステムの中心的なツールです。Mercurialコマンドと連携し、変更リスト（CL）の作成、アップロード、レビューコメントの処理、そして最終的なコミットを自動化します。

3. 変更リスト (Change List - CL):

   • Go言語のコードレビューシステムにおける「変更リスト（CL）」は、Gitにおけるプルリクエスト（Pull Request）やマージリクエスト（Merge Request）に相当する概念です。これは、一連の論理的に関連する変更（コミット）をまとめたもので、レビューのために提出されます。各CLには一意の番号が割り当てられます。
   • ユーザーは、hg mail <CL番号> や hg submit <CL番号> のように、CL番号を指定して特定の変更リストを操作します。

4. Pythonの文字列フォーマット:

   • Pythonでは、文字列内に変数の値を埋め込むために様々な方法があります。このコミットでは、% 演算子を使用した古いスタイルの文字列フォーマットが使われています。例えば、"no files changed (use hg %s <number> to use existing CL)" % op のように、%s の部分に変数 op の値が挿入されます。

これらの前提知識を理解することで、コミットが解決しようとしている問題と、その解決策がどのように実装されているかを深く把握することができます。

技術的詳細

このコミットの技術的な核心は、lib/codereview/codereview.py ファイル内の CommandLineCL 関数と、その関数が mail および submit 関数からどのように呼び出されるかの変更にあります。

1. CommandLineCL 関数のシグネチャ変更:

   • 変更前: def CommandLineCL(ui, repo, pats, opts, defaultcc=None):
   • 変更後: def CommandLineCL(ui, repo, pats, opts, op="verb", defaultcc=None):
   • 新しい引数 op が追加されました。この引数は、エラーメッセージ内で使用されるコマンド名（例: "mail" や "submit"）を動的に指定するために導入されました。デフォルト値は "verb" です。

2. エラーメッセージの改善:

   • CommandLineCL 関数内で、変更されたファイルがない場合に返されるエラーメッセージが変更されました。
   • 変更前: return None, "no files changed"
   • 変更後: return None, "no files changed (use hg %s <number> to use existing CL)" % op
   • この変更により、エラーメッセージに (use hg <command_name> <number> to use existing CL) というサジェスチョンが追加されました。<command_name> の部分には、op 引数で渡された値（mail または submit）が動的に挿入されます。

3. mail 関数と submit 関数からの CommandLineCL の呼び出し変更:

   • mail 関数内での呼び出し:
     • 変更前: cl, err = CommandLineCL(ui, repo, pats, opts, defaultcc=defaultcc)
     • 変更後: cl, err = CommandLineCL(ui, repo, pats, opts, op="mail", defaultcc=defaultcc)
   • submit 関数内での呼び出し:
     • 変更前: cl, err = CommandLineCL(ui, repo, pats, opts, defaultcc=defaultcc)
     • 変更後: cl, err = CommandLineCL(ui, repo, pats, opts, op="submit", defaultcc=defaultcc)
   • これにより、mail コマンドがエラーを発生させた場合は op="mail" が渡され、submit コマンドがエラーを発生させた場合は op="submit" が渡されるようになります。結果として、ユーザーは実行したコマンドに応じた正確なヒントを受け取ることができます。

この一連の変更により、ユーザーが hg mail や hg submit を誤った引数で実行した場合でも、システムが次に取るべきアクションを具体的に指示できるようになり、ユーザーエクスペリエンスが大幅に向上します。

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

diff --git a/lib/codereview/codereview.py b/lib/codereview/codereview.py
index c02f241d5c..3d7b9ad5b1 100644
--- a/lib/codereview/codereview.py
+++ b/lib/codereview/codereview.py
@@ -807,7 +807,7 @@ def EditCL(ui, repo, cl):
 # For use by submit, etc. (NOT by change)
 # Get change list number or list of files from command line.
 # If files are given, make a new change list.
-def CommandLineCL(ui, repo, pats, opts, defaultcc=None):
+def CommandLineCL(ui, repo, pats, opts, op="verb", defaultcc=None):
 	if len(pats) > 0 and GoodCLName(pats[0]):
 		if len(pats) != 1:
 			return None, "cannot specify change number and file names"
@@ -821,7 +821,7 @@ def CommandLineCL(ui, repo, pats, opts, defaultcc=None):
 		cl.local = True
 		cl.files = ChangedFiles(ui, repo, pats, taken=Taken(ui, repo))
 		if not cl.files:
-			return None, "no files changed"
+			return None, "no files changed (use hg %s <number> to use existing CL)" % op
 	if opts.get('reviewer'):
 		cl.reviewer = Add(cl.reviewer, SplitCommaSpace(opts.get('reviewer')))
 	if opts.get('cc'):
@@ -1792,7 +1792,7 @@ def mail(ui, repo, *pats, **opts):
 	if codereview_disabled:
 		raise hg_util.Abort(codereview_disabled)

-	cl, err = CommandLineCL(ui, repo, pats, opts, defaultcc=defaultcc)
+	cl, err = CommandLineCL(ui, repo, pats, opts, op="mail", defaultcc=defaultcc)
 	if err != "":
 		raise hg_util.Abort(err)
 	cl.Upload(ui, repo, gofmt_just_warn=True)
@@ -1881,7 +1881,7 @@ def submit(ui, repo, *pats, **opts):
 	if not opts["no_incoming"] and hg_incoming(ui, repo):
 		need_sync()

-	cl, err = CommandLineCL(ui, repo, pats, opts, defaultcc=defaultcc)
+	cl, err = CommandLineCL(ui, repo, pats, opts, op="submit", defaultcc=defaultcc)
 	if err != "":
 		raise hg_util.Abort(err)

コアとなるコードの解説

このコミットでは、主に3つの変更が行われています。

1. CommandLineCL 関数の引数追加:

   -def CommandLineCL(ui, repo, pats, opts, defaultcc=None):
   +def CommandLineCL(ui, repo, pats, opts, op="verb", defaultcc=None):
   

   CommandLineCL 関数は、コマンドライン引数から変更リスト（CL）の情報を解析する役割を担っています。この変更では、新しい引数 op が追加されました。この op は、エラーメッセージ内で使用されるコマンド名（例: mail や submit）を動的に挿入するために利用されます。デフォルト値として "verb" が設定されており、これは mail や submit 以外のコンテキストでこの関数が呼び出された場合の汎用的なプレースホルダーとして機能します。

2. エラーメッセージの変更:

   -			return None, "no files changed"
   +			return None, "no files changed (use hg %s <number> to use existing CL)" % op
   

   CommandLineCL 関数内で、ユーザーがファイル名を指定せずにコマンドを実行し、かつ変更されたファイルが見つからない場合に発生するエラーメッセージが変更されました。 変更前は単に「no files changed」（変更されたファイルがありません）と表示されていましたが、変更後は %s プレースホルダーを使用して op 引数の値（mail または submit）を埋め込み、「no files changed (use hg <コマンド名> <番号> to use existing CL)」という、より具体的なヒントを含むメッセージが表示されるようになりました。これにより、ユーザーは次に何をすべきか（既存のCL番号を指定してコマンドを再実行する）を明確に理解できます。

3. mail および submit 関数からの CommandLineCL 呼び出しの変更:

   -	cl, err = CommandLineCL(ui, repo, pats, opts, defaultcc=defaultcc)
   +	cl, err = CommandLineCL(ui, repo, pats, opts, op="mail", defaultcc=defaultcc)
   

   -	cl, err = CommandLineCL(ui, repo, pats, opts, defaultcc=defaultcc)
   +	cl, err = CommandLineCL(ui, repo, pats, opts, op="submit", defaultcc=defaultcc)
   

   mail 関数と submit 関数は、それぞれコードレビューの送信とコミットを行うためのエントリポイントです。これらの関数から CommandLineCL を呼び出す際に、新しく追加された op 引数にそれぞれのコマンド名（"mail" または "submit"）が明示的に渡されるようになりました。これにより、CommandLineCL 関数内で生成されるエラーメッセージが、実際にユーザーが実行したコマンド（hg mail または hg submit）に合わせた適切なサジェスチョンを含むようになります。

これらの変更は、Go言語のコードレビューツールのユーザビリティを向上させ、ユーザーがコマンドの誤用や引数不足に遭遇した際に、より効率的に問題解決できるよう支援することを目的としています。

関連リンク

• Go言語のコードレビューシステムに関する変更リスト: https://golang.org/cl/6924050

参考にした情報源リンク

• Mercurial 公式サイト: https://www.mercurial-scm.org/
• Go言語のコードレビュープロセスに関する情報 (当時の状況を理解するための一般的な情報源):
  • Go Wiki - CodeReview: https://go.dev/wiki/CodeReview (現在の情報ですが、当時のプロセスを推測するのに役立ちます)
• Python 文字列フォーマット:
  • Python公式ドキュメント - f-strings (現在の推奨): https://docs.python.org/3/tutorial/inputoutput.html#f-strings
  • Python公式ドキュメント - 古い文字列フォーマット演算子 (%): https://docs.python.org/3/library/stdtypes.html#printf-style-string-formatting (このコミットで使用されている形式)