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

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

このコミットは、Goプロジェクトの貢献ガイドラインを記述したdoc/contribute.htmlファイルを変更しています。このファイルは、Goプロジェクトにコードを貢献する開発者向けに、変更の作成、レビュー、アップロード、そして最終的なコミットまでの手順を説明する公式ドキュメントです。

コミット

このコミットは、Goプロジェクトへの貢献方法を説明するドキュメントdoc/contribute.htmlにおいて、記述されている手順の順序を「通常のワークフロー」に合わせるように変更しました。具体的には、コードレビューの依頼、レビューの実施、そして変更の修正と再アップロードに関するセクションの順序が調整されています。これにより、貢献者がより直感的かつ効率的にドキュメントを読み進め、Goプロジェクトへの貢献プロセスを理解できるようになりました。

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

https://github.com/golang/go/commit/822b2cbb33c5e15c4295998840310cfd8c14a4f5f

元コミット内容

doc/contribute: reorder documented steps to match normal workflow.

LGTM=adg
R=golang-codereviews, bradfitz, adg
CC=golang-codereviews
https://golang.org/cl/109970043

変更の背景

この変更の背景には、Goプロジェクトへの貢献プロセスをより明確にし、新規貢献者や既存の貢献者がドキュメントを読んだ際に、実際の作業フローとドキュメントの記述順序が一致するようにするという意図があります。元のドキュメントでは、コードレビューの依頼や修正のアップロードといった手順が、実際の開発ワークフローとは異なる順序で記述されていた可能性があります。このコミットは、ドキュメントの論理的な流れを改善し、貢献者が迷うことなくスムーズにプロセスを進められるようにするために行われました。

前提知識の解説

このコミットの変更内容を理解するためには、以下の前提知識が必要です。

  • Mercurial (Hg): Goプロジェクトはかつてバージョン管理システムとしてGitではなくMercurialを使用していました。hg change、hg mail、hg uploadといったコマンドはMercurialのコマンドであり、Goプロジェクトの貢献ワークフローにおいて重要な役割を担っていました。
    • hg change: 変更リスト（Change List, CL）を作成し、コードレビューシステムにアップロードするためのコマンド。
    • hg mail: 作成した変更リストをレビューのためにメーリングリストや特定のレビュアーに通知するためのコマンド。
    • hg upload: 変更リストをコードレビューシステムにアップロードするが、通知は行わないコマンド。主に修正後の再アップロードに使用されます。
  • Goのコードレビュープロセス: Goプロジェクトは、GoogleのGerritに似た独自のコードレビューシステム（AppEngineベースのcodereview.appspot.com）を使用していました。貢献者はhg changeで変更をアップロードし、hg mailでレビューを依頼します。レビュアーはウェブインターフェース上でコメントを付け、最終的にLGTM（Looks Good To Me）というコメントで承認します。
  • LGTM: "Looks Good To Me"の略で、コードレビューにおいてレビュアーが変更を承認する際に使用する一般的な略語です。Goプロジェクトのコードレビュープロセスでは、レビュアーがLGTMとコメントすることで、その変更が承認されたことを示していました。
  • CL (Change List): 変更リストの略で、Goプロジェクトにおける単一の論理的な変更単位を指します。これはGitにおけるコミットに似ていますが、コードレビューシステムと密接に連携しています。

技術的詳細

このコミットは、doc/contribute.html内のHTML構造を修正し、以下のセクションの順序を入れ替えています。

  1. Mail the change for review (変更をレビューのためにメールする): hg changeで変更をアップロードした後、レビュアーに通知するためのhg mailコマンドの使用方法を説明するセクション。
  2. Reviewing code (コードのレビュー): レビュアーがコードレビューシステム上で変更をレビューし、コメントを送信するプロセスを説明するセクション。
  3. Revise and upload (修正とアップロード): レビュアーのコメントに基づいてコードを修正し、再度レビューのためにアップロード（hg mailまたはhg upload）するプロセスを説明するセクション。

元のドキュメントでは、これらのセクションが実際のワークフローとは異なる順序で配置されていたため、読者が混乱する可能性がありました。このコミットでは、これらのセクションを、変更の作成→レビュー依頼→レビュー実施→修正と再アップロードという、より自然な流れに沿って再配置しています。これにより、ドキュメントが実際の開発プロセスをより正確に反映し、貢献者にとって理解しやすいものとなりました。

HTMLの変更は、主にこれらのセクションに対応する<h3>タグとその内容（<p>タグや<pre>タグで囲まれた説明とコード例）を、ファイル内で移動させることで実現されています。具体的には、元の位置からこれらのセクションを削除し、より適切な位置に挿入し直すという操作が行われています。

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

このコミットにおけるコアとなるコードの変更箇所は、doc/contribute.htmlファイル内の以下のHTMLセクションの移動です。

--- a/doc/contribute.html
+++ b/doc/contribute.html
@@ -312,6 +312,90 @@ which <code>hg change</code> will print, something like:
 CL created: https://codereview.appspot.com/99999
 </pre>
 
+<h3>Mail the change for review</h3>
+
+<p>
+Creating or uploading 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>To send out a change for review, run <code>hg mail</code> using the change list number
+assigned during <code>hg change</code>:</p>
+
+<pre>
+$ hg mail 99999
+</pre>
+
+<p>You can add to the <code>Reviewer:</code> and <code>CC:</code> lines
+using the <code>-r</code> or <code>--cc</code> options.
+In the above example, we could have left the <code>Reviewer</code> and <code>CC</code>
+lines blank and then run:</p>
+
+<pre>
+$ hg mail -r golang-codereviews@googlegroups.com --cc math-nuts@swtch.com 99999
+</pre>
+
+<p>to achieve the same effect.</p>
+
+<p>Note that <code>-r</code> and <code>--cc</code> cannot be spelled <code>--r</code> or <code>-cc</code>.</p>
+
+<p>
+If your change relates to an open issue, please add a comment to the issue
+announcing your proposed fix, including a link to your CL.
+</p>
+
+<h3>Reviewing code</h3>
+
+<p>
+Running <code>hg mail</code> will send an email to you and the reviewers
+asking them to visit the issue\'s URL and make comments on the change.
+When done, the reviewer clicks &ldquo;Publish and Mail comments&rdquo;
+to send comments back.
+</p>
+
+
+<h3>Revise and upload</h3>
+
+<p>
+When you have revised the code and are ready for another round of review,
+you can upload your change and send mail asking the reviewers to
+please take another look (<code>PTAL</code>). Use the change list number
+assigned during <code>hg change</code>
+</p>
+
+<pre>
+$ hg mail 99999
+</pre>
+
+
+<p>
+Or to upload your change without sending a notification, run
+</p>
+
+<pre>
+$ hg upload 99999
+</pre>
+
+<p>
+You will probably revise your code in response to the reviewer comments.
+You might also visit the code review web page and reply to the comments,
+letting the reviewer know that you\'ve addressed them or explain why you
+haven\'t.  When you\'re done replying, click &ldquo;Publish and Mail comments&rdquo;
+to send the line-by-line replies and any other comments.
+</p>
+
+<p>
+The reviewer can comment on the new copy, and the process repeats.
+The reviewer approves the change by replying with a mail that says
+<code>LGTM</code>: looks good to me.
+</p>
+
+<p>
+You can see a list of your pending changes by running <code>hg pending</code> (<code>hg p</code> for short).
+</p>
+
 <h3>Adding or removing files from an existing change</h3>
 
 <p>
@@ -433,90 +517,6 @@ changes, but you may still need to run
 <code>hg resolve -m</code> to mark the conflict resolved.\n </p>\n \n-<h3>Mail the change for review</h3>
-\n-<p>\n-Creating or uploading the change uploads a copy of the diff to the code review server,\n-but it does not notify anyone about it. To do that, you need to run <code>hg mail</code>\n-(see below).\n-</p>\n-\n-<p>To send out a change for review, run <code>hg mail</code> using the change list number\n-assigned during <code>hg change</code>:</p>\n-\n-<pre>\n-$ hg mail 99999\n-</pre>\n-\n-<p>You can add to the <code>Reviewer:</code> and <code>CC:</code> lines\n-using the <code>-r</code> or <code>--cc</code> options.\n-In the above example, we could have left the <code>Reviewer</code> and <code>CC</code>\n-lines blank and then run:\n-</p>\n-\n-<pre>\n-$ hg mail -r golang-codereviews@googlegroups.com --cc math-nuts@swtch.com 99999\n-</pre>\n-\n-<p>to achieve the same effect.</p>\n-\n-<p>Note that <code>-r</code> and <code>--cc</code> cannot be spelled <code>--r</code> or <code>-cc</code>.</p>\n-\n-<p>\n-If your change relates to an open issue, please add a comment to the issue\n-announcing your proposed fix, including a link to your CL.\n-</p>\n-\n-<h3>Reviewing code</h3>
-\n-<p>\n-Running <code>hg mail</code> will send an email to you and the reviewers\n-asking them to visit the issue\'s URL and make comments on the change.\n-When done, the reviewer clicks &ldquo;Publish and Mail comments&rdquo;\n-to send comments back.\n-</p>\n-\n-\n-<h3>Revise and upload</h3>
-\n-<p>\n-When you have revised the code and are ready for another round of review,\n-you can upload your change and send mail asking the reviewers to\n-please take another look (<code>PTAL</code>). Use the change list number\n-assigned during <code>hg change</code>\n-</p>\n-\n-<pre>\n-$ hg mail 99999\n-</pre>\n-\n-\n-<p>\n-Or to upload your change without sending a notification, run\n-</p>\n-\n-<pre>\n-$ hg upload 99999\n-</pre>\n-\n-<p>\n-You will probably revise your code in response to the reviewer comments.\n-You might also visit the code review web page and reply to the comments,\n-letting the reviewer know that you\'ve addressed them or explain why you\n-haven\'t.  When you\'re done replying, click &ldquo;Publish and Mail comments&rdquo;\n-to send the line-by-line replies and any other comments.\n-</p>\n-\n-<p>\n-The reviewer can comment on the new copy, and the process repeats.\n-The reviewer approves the change by replying with a mail that says\n-<code>LGTM</code>: looks good to me.\n-</p>\n-\n-<p>\n-You can see a list of your pending changes by running <code>hg pending</code> (<code>hg p</code> for short).\n-</p>\n-\n <h3>Reviewing code by others</h3>
 
 <p>

この差分は、doc/contribute.htmlの312行目付近に「Mail the change for review」「Reviewing code」「Revise and upload」の各セクションが追加され、433行目付近から同じ内容が削除されていることを示しています。これは、これらのセクションがファイル内で移動されたことを意味します。

コアとなるコードの解説

移動された各セクションは、Goプロジェクトへの貢献における重要なステップを説明しています。

  • Mail the change for review: このセクションは、hg changeコマンドで変更リストをアップロードした後、レビュアーにレビューを依頼するためにhg mailコマンドを使用する方法を説明しています。hg mailは、コードレビューサーバーにアップロードされた差分について、レビュアーに通知メールを送信する役割を担います。また、Reviewer:やCC:の行にレビュアーやCCを追加するためのオプション（-rや--cc）についても言及しています。さらに、関連するオープンなissueがある場合には、そのissueにCLへのリンクを含めてコメントを追加するよう促しています。
  • Reviewing code: このセクションは、レビュアーがコードレビューを行うプロセスを説明しています。hg mailによってレビュアーにメールが送信され、レビュアーは提供されたURLからコードレビューページにアクセスしてコメントを付けます。コメントを送信する際には「Publish and Mail comments」をクリックすることで、コメントが送信者に通知される仕組みになっています。
  • Revise and upload: このセクションは、レビュアーからのコメントを受けてコードを修正し、再度レビューのためにアップロードする手順を説明しています。修正後、貢献者は再びhg mailコマンドを使用してレビュアーに再レビューを依頼します。通知なしでアップロードしたい場合はhg uploadを使用することもできます。また、コードレビューのウェブページでコメントに返信し、修正内容を説明したり、なぜ修正しなかったかを説明したりするプロセスについても触れています。レビュアーが変更を承認する際には、LGTM（Looks Good To Me）というコメントを返信することが慣例となっています。最後に、hg pendingコマンド（またはhg p）で保留中の変更リストの一覧を確認できることも示されています。

これらのセクションを適切な順序に再配置することで、貢献者はGoプロジェクトのコードレビューと貢献のライフサイクルを、より自然な流れで理解できるようになりました。これは、ドキュメントのユーザビリティを向上させ、貢献プロセスを円滑にする上で重要な改善です。

関連リンク

参考にした情報源リンク

  • GoプロジェクトのGitHubリポジトリ: https://github.com/golang/go
  • Mercurialドキュメント (一般的なMercurialコマンドの理解のため)
  • Goプロジェクトの過去の貢献ガイドラインに関する情報 (Web検索を通じて、当時のGoプロジェクトの貢献ワークフローやツールに関する情報を収集)
  • コミットハッシュ: 822b2cbb33c5e15c429598840310cfd8c14a4f5f
  • GoLang Code Review System (codereview.appspot.com) に関する情報 (Web検索を通じて、当時のGoプロジェクトが使用していたコードレビューシステムの概要を理解するため)
  • LGTM (Looks Good To Me) の一般的な意味と使用法 (Web検索を通じて、コードレビューにおけるLGTMの慣習を理解するため)
  • CL (Change List) の概念 (Web検索を通じて、GoプロジェクトにおけるCLの役割を理解するため)