このドキュメントは、Goプロジェクトへ貢献するための方法を説明します。
ここでは、installation instructions
でGoをソースからインストールし、
書いた自分のソースコードをテストする術
を既に修得しているものと仮定します。
（gccgoは別のガイド:
Contributing to gccgo
を参照ください。）
Goプロジェクトではコミットを歓迎します、が、Goのメインリポジトリに取り込みたいのであれば、 あなたが取り組んでいることをみんなに知らせてください。
何か新しいことへ取り組む前に、 メーリングリスト へメールを送り、計画について議論してください。 これは、デザインを検証する機会をみんなに与え、同じことをしてしまうことを避け、 そして、言語やツールの目標に沿ったアイディアにしていく活動です。 また、コードが書かれる前にデザインが有効であることを保証します。 コードレビューツールは詳細な議論をする場ではありません。
要するに、コードの前にメールを送ってください。 そして、変更するためにチェンジリスト(change list)のメールで議論を始めないようにしてください。
あなたが書いたコードとテストは、 レビューに送る前に、他のパッケージやプログラムを破壊しない変更であることを 確かめるために、ツリー全体で全てのテストを実行します:
cd $GOROOT/src ./all.bash # On Windows, run all.bat
全体のテストを実施して、"ALL TESTS PASSED"が表示されればOKです。
Goへの変更は、誰が変更したとしても、 それがリポジトリへコミットされる前にレビューされる必要性があります。 （例外として、ビルドの修正のような場合は レビューはコミット後に手短にフォローします） Mercurialの拡張は、コードレビューのプロセスを管理するのに役に立ちます。 この拡張はGoのソースツリーに含んでいますので、 以下の手順に従ってMercurialの設定に追加してください。
注意:コードレビュー拡張で拡張したMercurialの使い方と、標準のMercurialの使い方は異なります。
Goのリポジトリは、レビューした変更点の単一ラインとして管理されています。
Mercurialでの変更グラフの複雑さを避けることを目的としています。
コードレビュー拡張で便利なのは: hg submit コマンドで、
リモートリポジトリと比較してローカルリポジトリが古くなっているか自動的にチェックし、警告します。
また、hg submitコマンドはGoリポジトリの他の項目について検証します。
例えば、Goのコードがgofmtで定義されている
標準スタイルでフォーマットされているか、
また、コードの著作がcopyright purposes
に沿って適切に記載されているかをチェックします。
hg submitで作成された変更のみを確実に支援するために、
標準のhg commitコマンドは無効になります。
$GOROOT/.hg/hgrcへ以下を追加します:
[extensions] codereview = $GOROOT/lib/codereview/codereview.py [ui] username = Your Name <[email protected]>
usernameの情報は、あなたがコミッター（下のセクションを参照）ではない限り利用されませんが、
これがないとMercurialから文句を言われます。
コードレビューの拡張を追加した後、まずは:
$ hg help codereview
として、このコマンドを修得してください。
特定のコードレビューコマンド（例えばchange）について学ぶためには次のように実行します:
$ hg help change
コードレビュー拡張は、$GOROOTの自分のチェックアウトだけで有効です。
よって、このドキュメントでのコマンドの実行は、$GOROOT内と想定しています。
Windowsユーザは、コードレビューの拡張を動作するために 追加の作業が必要です。 Go Wikiの CodeReview pageを参照してください。
コードレビューサーバは、認証のためGoogleアカウントが必要です。
（もしsign in at google.comでログインできるなら、コードレビューサーバへサインインできます。）
emailアドレスは、コードレビューサイト上で使え、
Mercurial change log
と
CONTRIBUTORSファイルへ記録されます。
なお、あなたが受信している任意のアドレスで
Google Accountを作成
することもできます。
二段階認証を有効にしている場合、アプリケーション固有のパスワードを生成し、
プロンプトでパスワードを使うことを忘れないようにしてください。
$ cd $GOROOT $ hg code-login Email (login for uploading to codereview.appspot.com): [email protected] Password for [email protected]: Saving authentication cookies to /Users/rsc/.codereview_upload_cookies_codereview.appspot.com
自分のcode review settingsを編集し、 ニックネームを取得してください。 レビュー時に多くの内容を受け取るために、 Contextオプションに“Whole file”をセットしておくのがオススメです。
一度、設定ページでニックネームを選んでおくと、 他の人は、レビュアーやCCリストへ、そのニックネームを使うことができるようになります。
ほとんどのGoインストールは、releaseブランチを使っていますが、 新しい変更はdefaultブランチだけにすべきです。 （ただ、リリースプロセスの一部としてreleaseブランチへ後で適用することもあります） 変更を入れる前に、必ずdefaultブランチを使ってください:
$ hg update default
チェックアウトしたツリー全体は、どこでも書き込み可能です。
ファイルを編集する必要があれば、単にそれを編集するだけです。
Mercurialは、その変更を把握しています。
なお、ファイルを追加(add)、削除(remove)、コピー(copy)、リネーム(rename)は、
Mercurialへ知らせるために、
hg add、
hg rm、
hg cp、
hg mv
を使ってください。
変更をレビューへ送る準備ができたら、自分のGoリポジトリの任意の場所から:
$ hg change
を実行します。
するとMercurialは、あなたのエディタで変更の説明を書くためのファイルを開きます
（これは、環境変数の$EDITORに設定してあるエディタを使います。
デフォルトではviです）。
例えば、開かれたファイルはこのようなものです:
# Change list. # Lines beginning with # are ignored. # Multi-line values should be indented. Reviewer: CC: Description: <enter description here> Files: src/pkg/math/sin.go src/pkg/math/tan.go src/pkg/regexp/regexp.go
Reviewerは、この変更へアサインするレビュアーをリストし、
CCは、変更について知らせたい人をリストします。
これらは、コードレビューのニックネームや、任意のemailアドレスを使えます。
チェンジリスト(change list)を送るに至るまでの議論で
明示的に言われない限り、
レビュアーは空欄のままにします。
これは、レビュアーとして
[email protected]
のメーリングリストを使うことを意味します。
“<enter description here>”
を、あなたの変更の説明で置き換えてください。
説明の最初の行は、影響するパッケージを先頭に、一行で変更の要約を書くようにします。
コードレビューのメールのための議題としても使われます。
次の行からは詳しい内容をすきなだけ書いてください。
Filesセクションは、
あなたの変更のすべてのファイルをリストしています。
関連のない変更は、他のチェンジリストにしましょう。
例では、
regexp.goの行を削除することで、
mathパッケージへの変更だけにしています。
編集後、テンプレートはこのようになりました:
# Change list. # Lines beginning with # are ignored. # Multi-line values should be indented. Reviewer: [email protected] CC: [email protected] Description: math: improved Sin, Cos and Tan precision for very large arguments. See Bimmler and Shaney, ``Extreme sinusoids,'' J. Math 3(14). Fixes issue 159. Files: src/pkg/math/sin.go src/pkg/math/tan.go
“Fixes issue 159.” というのは、 Go issue tracker の issue 159 に関連する変更であることを意味する特別な文です。 この変更が最終的に投稿されたとき、 issue trackerはissueをfixedとして自動的に記録します （この詳細な使い方については、 Google Project Hosting Issue Tracker documentation に記載されています）。
それでは、ファイルを保存して、エディタを終了します。
hg changeで、
コードレビューサーバはあなたの変更へissue番号とURLを割り当て、
次のように出力します:
CL created: https://codereview.appspot.com/99999
もし、チェンジリスト(CL)を再編集したり、CLへ更新ファイルを追加する必要がある時は、
hg change 99999
を実行します。
他の方法は、
$ hg file 99999 somefile
で、CL 99999へsomefileを追加し、
$ hg file -d 99999 somefile
で、CLからsomefileを削除します。
ファイルは、ひとつのアクティブなCLだけへ属すことができます。
hg fileは、
もしファイルが変更の間で移動される際に警告を出すでしょう。
あなたが作業している間に、他の人からリポジトリへ変更のコミットがあることでしょう。 クライアントでアップデートするためには:
$ hg sync
を実行します。
（Mercurialユーザのために補足すると、
hg sync
は
hg pull -u
を実行しますが、
新しいデータに対し、ローカルのチェンジリストの状態も同期しています）
あなたが編集していたファイルが変更されている場合、 Mercurialはローカルの変更に対し、リモートの変更をマージ（merge） を試みます。 いくつかのファイルは人の手でマージするために残るかもしれません。
例えば、
あなたの手元に編集したflag_test.goがあるとします。
しかし、他の誰かが別の変更をコミットしました。
hg syncを実行すると、次のような（ヒドイ）結果を得る（強調を追加しています）でしょう:
$ hg sync adding changesets adding manifests adding file changes added 1 changeset with 2 changes to 2 files getting src/pkg/flag/flag.go couldn't find merge tool hgmerge merging src/pkg/flag/flag_test.go warning: conflicts during merge. merging src/pkg/flag/flag_test.go failed! 1 file updated, 0 files merged, 0 files removed, 1 file unresolved use 'hg resolve' to retry unresolved file merges $
重要な部分はイタリックの行で、
「Mercurialは別の変更であなたの変更をマージすることに失敗した」
ということを伝えています。
これが発生すると、
Mercurialは、ファイルに両方の編集内容を
<<<<<<<と
>>>>>>>のマークで記録します。
マージするために、このファイルの編集が必要です。
例で話を続けると、
flag_test.goでこれら文字列を検索すると
次のようになっているかもしれません:
VisitAll(visitor);
<<<<<<< local
if len(m) != 7 {
=======
if len(m) != 8 {
>>>>>>> other
t.Error("VisitAll misses some flags");
Mercurialは オリジナルのテキストは6で、あなたは1追加し、別の変更では2追加しています。 ですので、正しい修正は9と考えることができます。 では、マークを取り除き、正しいコードを書きます:
VisitAll(visitor);
if len(m) != 9 {
t.Error("VisitAll misses some flags");
そして、Mercurialへコンフリクト(conflict)を解決(resolve)したことを伝えます:
$ hg resolve -m flag_test.go
デバッグのためにファイルを編集してしまっても
編集内容を保管することを気にしなくても大丈夫です。
編集内容を破棄するためには
hg revert flag_test.go
が利用できますが、
hg resolve -m
をコンフリクトを解決したことを記録するために実行する必要があります。
変更の作成、更新の操作は、コードレビューサーバへdiffのコピーをアップロードしますが、
これについては誰にも通知しません。
通知するためには、
hg mail
を実行する必要があります)。
変更をレビューへ送るために、
hg change
の時に割り当てられたチェンジリストの番号を使って
hg mail
を実行します:
$ hg mail 99999
Reviewer:と
CC:は、
それぞれオプションの
-rと
--ccで追加することができます。
上の例では、
Reviewerと
CCの行を空っぽにして次のように実行できます:
$ hg mail -r [email protected] --cc [email protected] 99999
これで同じ意味になります。
-rと
--ccは、
--rや
-ccのスペルでは使用できないことに注意してください。
あなたの変更が未解決(open)のissueに関連している場合は、 issueへあなたの提案した修正を CLへのリンクを含め、 issueのアナウンスへ コメントを追加してください。
hg mailは、
issueへのURLと変更へコメントをレビュアーに求めるための内容を
あなたとレビュアーへemailで送ります（訳注1）。
レビューを完了したら、レビュアーはページにある
“Publish and Mail comments”
をクリックしてコメントを返します。
おそらく、レビュアーのコメントに応じてコードを見直すと思います。
見直しが終われば、
hg change
で割り当てられたチェンジリストの番号を使って
hg upload
で通知せずに
コードレビューサーバへ変更をアップロードします。
$ hg upload 99999
コードの見直しが完了し、レビューの準備が整ったなら:
$ hg mail 99999
で再び最新のコードをアップロードし、レビュアーへ
please take another look (PTAL)
依頼をメールします。
コードレビューのウェブページへ訪れ、
あなたがそれに対処してきたことをレビュアーへ知らせたり、また、なぜそうしなかったのかについて
コメントを返信するほうがいいかもしれません。
返信が終われば、
“Publish and Mail comments”
をクリックして、行へ返信したり他のコメントを返したりします。
レビュアーは、新しいコピーへコメントでき、このプロセスを繰り返すことができます。
そして、レビュアーは、LGTM(looks good to me)と言ってメールを返すことで
変更内容を受け入れます。
hg pending (hg p)
を実行して、あなたの保留中(pending)のリストを表示できます。
hg clpatchコマンド
で、誰かのチェンジリストを自分のMercurialクライアントへインポートすることができます。
例えば:
$ hg clpatch 99999
で、
CL 99999
の最新の差分が手元へ適用されます。
CL 99999
で参照しているファイルのいずれかへ、既に手元のファイルへ変更がある場合、
clpatchは全体への適用を中止します。
一度適用すると、
hg pending
などの出力へ
CL 99999
が表示されるようになります。
手元に適用したCLを元に戻す(revert)なら、
hg revert
コマンドを使います。
$ hg revert @99999
として、 CL 99999 のオリジナルの状態へファイルを戻せます。 これは、CLのリビジョンを戻したり、他のを適用してみたりする際に効果を発揮します。
CLをコミットし終わった後、
hg sync
を実行すると、ローカルの保留中(pending)のリストからそれが削除されます。
ときどき、提案を取りやめていたり、放棄されているCLの同期をやめたいことがあります。
そんなときは、
hg change -D 99999
で
CL 99999
への参照を除去できます。
LGTM
としてもらえたら、いよいよMercurialリポジトリへ入れる時です。
もしあなたがコミッター(committer)でなければ、
変更を直接コミットできません。
代わりに、コミッターがレビュアーから
LGTM
としてもらったものに対して:
$ hg clpatch 99999 $ hg submit 99999
とします。
submitは、コードをリポジトリへ入れるコマンドです。
コミットのAutherはあなたの名前で、誰がコミッターだったかを示すメッセージがログに記録されます。
次に
hg sync
を実行したときに、変更がコミットされたことを知らせてくれます。
もし、あなたがコミッターなら:
$ hg submit 99999
を実行します。 これで、変更内容にコードレビューのリンクが記載され、 コードレビュー上は、リポジトリへコミットされた内容のリンクで更新されます。
ローカルが古くなっている場合、
hg submitはsyncするように促してきます:
$ hg submit 99999 local repository out of date; must sync before submit
Goのリポジトリ内のファイルには作者(author)の名前を記載しません。
これは、最新のリストを維持することで混乱してしまうことを避けるためです。
代わりに、あなたの名前は
Mercurialのチェンジログ
に記載され、さらに
CONTRIBUTORS
ファイルと
AUTHORS
に記載されるようになります。
CONTRIBUTORS
ファイルは、Goへ貢献した人たちが誰かを定義し、
AUTHORS
ファイルは、Goの著作の保有者たちが誰かを定義しています。
GoogleのGoのデベロッパーにより、これらのファイルは、あなたの初めてのコミットで更新されます。
これをできるようにするために、以下のcontributor license agreementsのいずれかをしておく必要があります。
この面倒な手続きは、初めてのコミットにだけ必要です。
標準の著作表示のヘッダは、以下を使うようにしてください:
// Copyright 2014 The Go Authors. All rights reserved. // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file.
ファイルをリポジトリへ追加した年を入れます。 ファイルを更新する度に年を更新する必要はありません。
翻訳メモ: submit=コミットと翻訳しています
訳注1: emailはコードレビューサーバから送信されます。
本ドキュメントは以下のドキュメントを翻訳しています: https://code.google.com/p/go/source/browse/doc/contribute.html?r=086daa1d2552d1aa3a6ec3c6d61f72ddc107e52c