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

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

このコミットは、Goプロジェクトの貢献ガイドラインを記述したdoc/contribute.htmlファイルを変更しています。

コミット

commit d5f208c8746a92fa889b9a9121e0d40dcc1deced
Author: Nathan John Youngman <nj@nathany.com>
Date:   Mon Mar 17 09:35:04 2014 +1100

    doc: Revise Contribution Guidelines.
    
    Smooth out the setup process for new contributors.
    
    * Remove references $GOROOT (often not defined).
    * Add a note for contributing to subrepositories.
    * Emphasize that hg mail also uploads the latest copy.
    
    LGTM=adg
    R=golang-codereviews, iant, adg
    CC=golang-codereviews
    https://golang.org/cl/74370043

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

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

元コミット内容

doc: Revise Contribution Guidelines.

Smooth out the setup process for new contributors.

* Remove references $GOROOT (often not defined).
* Add a note for contributing to subrepositories.
* Emphasize that hg mail also uploads the latest copy.

LGTM=adg
R=golang-codereviews, iant, adg
CC=golang-codereviews
https://golang.org/cl/74370043

変更の背景

このコミットの主な目的は、Goプロジェクトへの新規貢献者が開発環境をセットアップし、コードを提出するプロセスをよりスムーズにすることです。具体的には、以下の3つの課題に対処しています。

  1. $GOROOTの参照の削除: 以前の貢献ガイドラインでは、$GOROOT環境変数を頻繁に参照していましたが、これは常に定義されているとは限らず、特に新規ユーザーにとっては混乱の原因となっていました。この変更により、より一般的なパス（例: go/src）を使用するように修正され、セットアップの障壁が低減されました。
  2. サブリポジトリへの貢献に関する注意点の追加: Goプロジェクトは、メインのGoリポジトリだけでなく、go.toolsのようなサブリポジトリも持っています。これらのサブリポジトリへの貢献方法について明確な指示がなかったため、新規貢献者が戸惑う可能性がありました。このコミットでは、サブリポジトリへの貢献に関する具体的な手順が追加されました。
  3. hg mailの動作の明確化: Goプロジェクトでは、コードレビューにMercurial (hg) の拡張機能であるcodereviewを使用しており、変更をアップロードするためにhg uploadとhg mailコマンドが使われていました。しかし、hg mailが単にメールを送信するだけでなく、最新の変更もアップロードするという重要な側面が十分に強調されていませんでした。この変更により、この点が明確にされ、レビュープロセスにおける混乱が解消されました。

これらの変更は、Goコミュニティへの参加を促進し、貢献プロセスのユーザビリティを向上させることを目的としています。

前提知識の解説

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

  • Go言語の環境変数 $GOROOT: $GOROOTは、Goのインストールディレクトリを指す環境変数です。Go 1.0からGo 1.7までは、Goのソースコードや標準ライブラリがこのディレクトリに配置されていました。しかし、Go 1.8以降では、$GOROOTを明示的に設定する必要はほとんどなくなり、Goツールチェーンが自動的にGoのインストールパスを検出するようになりました。このコミットが作成された2014年時点では、$GOROOTはまだ重要な概念でしたが、新規ユーザーにとっては設定が必須ではない場合もあり、混乱を招くことがありました。

  • Mercurial (Hg): Mercurialは、Gitと同様の分散型バージョン管理システム（DVCS）です。Goプロジェクトは、初期にはMercurialを使用してソースコードを管理していました。Mercurialは、リポジトリのクローン、コミット、プッシュ、プルなどの基本的なバージョン管理操作を提供します。Goプロジェクトでは、Mercurialの拡張機能を利用してコードレビュープロセスを統合していました。

  • Goのコードレビュープロセスと codereview 拡張機能: Goプロジェクトでは、Googleが開発したcodereviewというMercurial拡張機能を使用してコードレビューを行っていました。これは、変更をアップロードし、レビューコメントを受け取り、変更を修正して再アップロードするための一連のコマンドを提供します。

    • hg change: 新しい変更セット（チェンジリスト）を作成し、レビューのために準備します。
    • hg upload: 作成した変更セットをコードレビューサーバー（codereview.appspot.comなど）にアップロードします。このコマンドは、変更をアップロードするだけで、レビュー担当者への通知メールは送信しません。
    • hg mail: 変更セットをコードレビューサーバーにアップロードし、同時にレビュー担当者への通知メールを送信します。このコマンドは、hg uploadの機能を含んでおり、レビュー担当者に「もう一度見てください（PTAL: Please Take Another Look）」というリクエストを送る際に使用されます。

  • Goのサブリポジトリ: Goプロジェクトは、メインのGoリポジトリ（golang/go）の他に、特定の機能やツールを提供する複数のサブリポジトリ（例: golang.org/x/tools、golang.org/x/netなど）を持っています。これらは独立したリポジトリとして管理されていますが、Goエコシステムの一部として密接に関連しています。貢献者は、これらのサブリポジトリに対しても個別に貢献を行うことができます。

技術的詳細

このコミットは、doc/contribute.htmlファイル内の複数のセクションにわたって変更を加えています。

  1. $GOROOT参照の削除とパスの明確化:

    • 変更前: cd $GOROOT/src
    • 変更後: cd go/src
    • 変更前: codereview = $GOROOT/lib/codereview/codereview.py
    • 変更後: codereview = /path/to/go/lib/codereview/codereview.py
    • 変更前: As the codereview extension is only enabled for your checkout in $GOROOT, the remainder of this document assumes you are inside $GOROOT when issuing commands.
    • 変更後: As the codereview extension is only enabled for your Go checkout, the remainder of this document assumes you are inside the go directory when issuing commands. これらの変更により、$GOROOT環境変数が設定されていない環境でも、Goのソースディレクトリへの移動やcodereview拡張機能の設定がより直感的に行えるようになりました。絶対パスの代わりに相対パスや一般的なディレクトリ名を使用することで、新規ユーザーのセットアッププロセスが簡素化されます。

  2. サブリポジトリへの貢献に関する指示の追加:

    • 新しい段落が追加されました: To contribute to subrepositories, edit the .hg/hgrc for each subrepository in the same way. For example, add the codereview extension to code.google.com/p/go.tools/.hg/hgrc. この追加により、メインリポジトリだけでなく、サブリポジトリに対しても同様のcodereview拡張機能の設定が必要であることが明確に示され、貢献者がサブリポジトリに貢献する際のガイドラインが提供されました。

  3. hg mailとhg uploadの動作の明確化:

    • 変更前は、hg uploadで変更をアップロードし、その後hg mailで通知を送るという流れが示唆されていました。
    • 変更後: 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 (PTAL). Use the change list number assigned during hg change $ hg mail 99999 Or to upload your change without sending a notification, run $ hg upload 99999 この変更により、hg mailコマンドが「変更のアップロード」と「レビュー担当者への通知メール送信」の両方を一度に行うことが明確にされました。また、通知なしでアップロードしたい場合はhg uploadを使用するという選択肢も明確に提示されました。これにより、レビュープロセスのステップがより分かりやすくなりました。

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

--- a/doc/contribute.html
+++ b/doc/contribute.html
@@ -45,10 +45,14 @@ tree to make sure the changes don't break other packages or programs:
 </p>
 
 <pre>
-cd $GOROOT/src
-./all.bash    # On Windows, run all.bat
+$ cd go/src
+$ ./all.bash
 </pre>
 
+<p>
+(To build under Windows use <code>all.bat</code>.)
+</p>
+
 <p>
 After running for a while, the command should print "<code>ALL TESTS PASSED</code>".
 </p>
@@ -95,11 +99,11 @@ command.
 
 <h3>Configure the extension</h3>
 
-<p>Edit <code>$GOROOT/.hg/hgrc</code> to add:</p>
+<p>Edit <code>.hg/hgrc</code> in the root of your Go checkout to add:</p>
 
 <pre>
 [extensions]
-codereview = $GOROOT/lib/codereview/codereview.py
+codereview = /path/to/go/lib/codereview/codereview.py
 
 [ui]
 username = Your Name &lt;you@server.dom&gt;
@@ -110,6 +114,16 @@ The <code>username</code> information will not be used unless
 you are a committer (see below), but Mercurial complains if it is missing.
 </p>
 
+<p>
+As the codereview extension is only enabled for your Go checkout, the remainder of this document assumes you
+are inside the go directory when issuing commands.
+</p>
+
+<p>To contribute to subrepositories, edit the <code>.hg/hgrc</code> for each
+subrepository in the same way. For example, add the codereview extension to
+<code>code.google.com/p/go.tools/.hg/hgrc</code>.
+</p>
+
 <h3>Understanding the extension</h3>
 
 <p>After adding the code review extension, you can run</p>
@@ -126,15 +140,9 @@ $ hg help change
 </pre>
 
 <p>
-As the codereview extension is only enabled for your checkout
-in <code>$GOROOT</code>, the remainder of this document assumes you
-are inside <code>$GOROOT</code> when issuing commands.
-</p>
-
-<p>
-Windows users may need to perform extra steps to get the code review 
+Windows users may need to perform extra steps to get the code review
 extension working. See the
-<a href="https://code.google.com/p/go-wiki/wiki/CodeReview">CodeReview page</a> 
+<a href="https://code.google.com/p/go-wiki/wiki/CodeReview">CodeReview page</a>
 on the <a href="https://code.google.com/p/go-wiki/wiki">Go Wiki</a> for details.
 </p>
 
@@ -155,7 +163,6 @@ application-specific password and use that when prompted for a password.\n </p>\n \n <pre>\n-$ cd $GOROOT\n $ hg code-login\n Email (login for uploading to codereview.appspot.com): rsc@golang.org\n Password for rsc@golang.org:\n@@ -473,31 +480,33 @@ to send comments back.\n <h3>Revise and upload</h3>\n \n <p>\n-You will probably revise your code in response to the reviewer comments. When\n-you have done this, you can upload your change to the code review server\n-without sending a notification by running <code>hg upload</code> using the change\n-list number assigned during <code>hg change</code>\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 upload 99999\n+$ hg mail 99999\n </pre>\n \n+\n <p>\n-When you have revised the code and are ready for another round of review, run\n+Or to upload your change without sending a notification, run\n </p>\n \n <pre>\n-$ hg mail 99999\n+$ hg upload 99999\n </pre>\n \n-<p>again to upload the latest copy and send mail asking the reviewers to please take another look\n-(<code>PTAL</code>).\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```

## コアとなるコードの解説

*   **`cd $GOROOT/src` から `cd go/src` への変更**:
    これは、Goのソースコードディレクトリへの移動方法をより汎用的にするための変更です。`$GOROOT`が常に設定されているとは限らないため、Goのチェックアウトのルートディレクトリから相対的に`go/src`に移動する方が、新規ユーザーにとって分かりやすくなります。

*   **`codereview = $GOROOT/lib/codereview/codereview.py` から `codereview = /path/to/go/lib/codereview/codereview.py` への変更**:
    `codereview`拡張機能のパス指定も同様に、`$GOROOT`への依存をなくし、ユーザーがGoのインストールパスを明示的に指定するように促しています。これにより、環境変数に依存しない、より堅牢な設定方法が提供されます。

*   **`As the codereview extension is only enabled for your checkout in $GOROOT, the remainder of this document assumes you are inside $GOROOT when issuing commands.` の削除と新しい説明の追加**:
    `$GOROOT`に関する古い説明を削除し、`As the codereview extension is only enabled for your Go checkout, the remainder of this document assumes you are inside the go directory when issuing commands.`という新しい説明を追加しています。これは、`codereview`拡張機能がGoのチェックアウトディレクトリでのみ有効であること、そしてコマンドを実行する際にはそのディレクトリ内にいることを前提としていることを明確にしています。これにより、ユーザーはどのディレクトリでコマンドを実行すべきかを理解しやすくなります。

*   **サブリポジトリに関する新しい段落の追加**:
    `To contribute to subrepositories, edit the .hg/hgrc for each subrepository in the same way. For example, add the codereview extension to code.google.com/p/go.tools/.hg/hgrc.`
    この追加は、Goのサブリポジトリへの貢献方法に関する重要なガイダンスを提供します。各サブリポジトリに対しても個別に`codereview`拡張機能を設定する必要があることを明示し、具体的な例（`code.google.com/p/go.tools/.hg/hgrc`）を挙げることで、ユーザーが迷うことなく設定できるようにしています。

*   **`hg mail`と`hg upload`の動作に関する説明の修正**:
    以前の説明では、`hg upload`でアップロードし、その後`hg mail`で通知を送るという誤解を招く可能性がありました。新しい説明では、`hg mail`が「変更のアップロード」と「レビュー担当者への通知メール送信」の両方を一度に行うことを明確にしています。
    `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 (PTAL). Use the change list number assigned during hg change`
    `$ hg mail 99999`
    `Or to upload your change without sending a notification, run`
    `$ hg upload 99999`
    この修正により、レビュー担当者に再レビューを依頼する際には`hg mail`を使用し、通知なしで単に最新の変更をアップロードしたい場合には`hg upload`を使用するという、それぞれのコマンドの正しい使い分けが明確になりました。これにより、レビュープロセスの効率と透明性が向上します。

## 関連リンク

*   Go Code Review Wiki Page (参照されているGo Wikiのページ): [https://code.google.com/p/go-wiki/wiki/CodeReview](https://code.google.com/p/go-wiki/wiki/CodeReview) (注: このリンクは古いGo Wikiのものであり、現在はGoの公式ドキュメントやGitHubベースのレビュープロセスに移行しています。)
*   Go Wiki (参照されているGo Wikiのトップページ): [https://code.google.com/p/go-wiki/wiki](https://code.google.com/p/go-wiki/wiki) (注: 同上)
*   Go Change List (CL) 74370043: [https://golang.org/cl/74370043](https://golang.org/cl/74370043)

## 参考にした情報源リンク

*   Mercurial Documentation (Mercurialの基本的なコマンドや概念について): [https://www.mercurial-scm.org/](https://www.mercurial-scm.org/)
*   Go Contribution Guidelines (現在のGoの貢献ガイドライン): [https://go.dev/doc/contribute](https://go.dev/doc/contribute) (このコミットの時点とは内容が異なりますが、現在の最新情報として参考になります。)
*   Go Environment Variables (Goの環境変数に関する公式ドキュメント): [https://go.dev/doc/install/source#environment](https://go.dev/doc/install/source#environment)
*   Go Subrepositories (Goのサブリポジトリに関する情報): [https://go.dev/wiki/SubRepositories](https://go.dev/wiki/SubRepositories)