...
Run Format

Contribution Guidelines

Introduction

このドキュメントは、Goプロジェクトへ貢献するための方法を説明します。 ここでは、installation instructions でGoをソースからインストールし、 書いた自分のソースコードをテストする術 を既に修得しているものと仮定します。 (gccgoは別のガイド: Contributing to gccgo を参照ください。)

Discuss your design

Goプロジェクトではコミットを歓迎します、が、Goのメインリポジトリに取り込みたいのであれば、 あなたが取り組んでいることをみんなに知らせてください。

何か新しいことへ取り組む前に、 メーリングリスト へメールを送り、計画について議論してください。 これは、デザインを検証する機会をみんなに与え、同じことをしてしまうことを避け、 そして、言語やツールの目標に沿ったアイディアにしていく活動です。 また、コードが書かれる前にデザインが有効であることを保証します。 コードレビューツールは詳細な議論をする場ではありません。

要するに、コードの前にメールを送ってください。 そして、変更するためにチェンジリスト(change list)のメールで議論を始めないようにしてください。

Testing redux

あなたが書いたコードとテストは、 レビューに送る前に、他のパッケージやプログラムを破壊しない変更であることを 確かめるために、ツリー全体で全てのテストを実行します:

cd $GOROOT/src
./all.bash    # On Windows, run all.bat

全体のテストを実施して、"ALL TESTS PASSED"が表示されればOKです。

Code review

Goへの変更は、誰が変更したとしても、 それがリポジトリへコミットされる前にレビューされる必要性があります。 (例外として、ビルドの修正のような場合は レビューはコミット後に手短にフォローします) Mercurialの拡張は、コードレビューのプロセスを管理するのに役に立ちます。 この拡張はGoのソースツリーに含んでいますので、 以下の手順に従ってMercurialの設定に追加してください。

Caveat for Mercurial aficionados

注意:コードレビュー拡張で拡張したMercurialの使い方と、標準のMercurialの使い方は異なります。

Goのリポジトリは、レビューした変更点の単一ラインとして管理されています。 Mercurialでの変更グラフの複雑さを避けることを目的としています。 コードレビュー拡張で便利なのは: hg submit コマンドで、 リモートリポジトリと比較してローカルリポジトリが古くなっているか自動的にチェックし、警告します。 また、hg submitコマンドはGoリポジトリの他の項目について検証します。 例えば、Goのコードがgofmtで定義されている 標準スタイルでフォーマットされているか、 また、コードの著作がcopyright purposes に沿って適切に記載されているかをチェックします。

hg submitで作成された変更のみを確実に支援するために、 標準のhg commitコマンドは無効になります。

Configure the extension

$GOROOT/.hg/hgrcへ以下を追加します:

[extensions]
codereview = $GOROOT/lib/codereview/codereview.py

[ui]
username = Your Name <you@server.dom>

usernameの情報は、あなたがコミッター(下のセクションを参照)ではない限り利用されませんが、 これがないとMercurialから文句を言われます。

Understanding the extension

コードレビューの拡張を追加した後、まずは:

$ hg help codereview

として、このコマンドを修得してください。 特定のコードレビューコマンド(例えばchange)について学ぶためには次のように実行します:

$ hg help change

コードレビュー拡張は、$GOROOTの自分のチェックアウトだけで有効です。 よって、このドキュメントでのコマンドの実行は、$GOROOT内と想定しています。

Windowsユーザは、コードレビューの拡張を動作するために 追加の作業が必要です。 Go WikiCodeReview pageを参照してください。

Log in to the code review site.

コードレビューサーバは、認証のためGoogleアカウントが必要です。 (もしsign in at google.comでログインできるなら、コードレビューサーバへサインインできます。) emailアドレスは、コードレビューサイト上で使え、 Mercurial change logCONTRIBUTORSファイルへ記録されます。 なお、あなたが受信している任意のアドレスで Google Accountを作成 することもできます。 二段階認証を有効にしている場合、アプリケーション固有のパスワードを生成し、 プロンプトでパスワードを使うことを忘れないようにしてください。

$ cd $GOROOT
$ hg code-login
Email (login for uploading to codereview.appspot.com): rsc@golang.org
Password for rsc@golang.org:

Saving authentication cookies to /Users/rsc/.codereview_upload_cookies_codereview.appspot.com

Configure your account settings.

自分のcode review settingsを編集し、 ニックネームを取得してください。 レビュー時に多くの内容を受け取るために、 Contextオプションに“Whole file”をセットしておくのがオススメです。

一度、設定ページでニックネームを選んでおくと、 他の人は、レビュアーやCCリストへ、そのニックネームを使うことができるようになります。

Switch to the default branch

ほとんどのGoインストールは、releaseブランチを使っていますが、 新しい変更はdefaultブランチだけにすべきです。 (ただ、リリースプロセスの一部としてreleaseブランチへ後で適用することもあります) 変更を入れる前に、必ずdefaultブランチを使ってください:

$ hg update default

Make a change

チェックアウトしたツリー全体は、どこでも書き込み可能です。 ファイルを編集する必要があれば、単にそれを編集するだけです。 Mercurialは、その変更を把握しています。 なお、ファイルを追加(add)、削除(remove)、コピー(copy)、リネーム(rename)は、 Mercurialへ知らせるために、 hg addhg rmhg cphg 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)を送るに至るまでの議論で 明示的に言われない限り、 レビュアーは空欄のままにします。 これは、レビュアーとして golang-codereviews@googlegroups.com のメーリングリストを使うことを意味します。

<enter description here>” を、あなたの変更の説明で置き換えてください。 説明の最初の行は、影響するパッケージを先頭に、一行で変更の要約を書くようにします。 コードレビューのメールのための議題としても使われます。 次の行からは詳しい内容をすきなだけ書いてください。

Filesセクションは、 あなたの変更のすべてのファイルをリストしています。 関連のない変更は、他のチェンジリストにしましょう。 例では、 regexp.goの行を削除することで、 mathパッケージへの変更だけにしています。

編集後、テンプレートはこのようになりました:

# Change list.
# Lines beginning with # are ignored.
# Multi-line values should be indented.

Reviewer: golang-codereviews@googlegroups.com
CC: math-nuts@swtch.com

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

Adding or removing files from an existing change

もし、チェンジリスト(CL)を再編集したり、CLへ更新ファイルを追加する必要がある時は、 hg change 99999 を実行します。

他の方法は、

$ hg file 99999 somefile

で、CL 99999へsomefileを追加し、

$ hg file -d 99999 somefile

で、CLからsomefileを削除します。

ファイルは、ひとつのアクティブなCLだけへ属すことができます。 hg fileは、 もしファイルが変更の間で移動される際に警告を出すでしょう。

Synchronize your client

あなたが作業している間に、他の人からリポジトリへ変更のコミットがあることでしょう。 クライアントでアップデートするためには:

$ hg sync

を実行します。 (Mercurialユーザのために補足すると、 hg synchg 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 をコンフリクトを解決したことを記録するために実行する必要があります。

Mail the change for review

変更の作成、更新の操作は、コードレビューサーバへdiffのコピーをアップロードしますが、 これについては誰にも通知しません。 通知するためには、 hg mail を実行する必要があります)。

変更をレビューへ送るために、 hg change の時に割り当てられたチェンジリストの番号を使って hg mail を実行します:

$ hg mail 99999

Reviewer:CC:は、 それぞれオプションの -r--ccで追加することができます。 上の例では、 ReviewerCCの行を空っぽにして次のように実行できます:

$ hg mail -r golang-codereviews@googlegroups.com --cc math-nuts@swtch.com 99999

これで同じ意味になります。

-r--ccは、 --r-ccのスペルでは使用できないことに注意してください。

あなたの変更が未解決(open)のissueに関連している場合は、 issueへあなたの提案した修正を CLへのリンクを含め、 issueのアナウンスへ コメントを追加してください。

Reviewing code

hg mailは、 issueへのURLと変更へコメントをレビュアーに求めるための内容を あなたとレビュアーへemailで送ります(訳注1)。 レビューを完了したら、レビュアーはページにある “Publish and Mail comments” をクリックしてコメントを返します。

Revise and upload

おそらく、レビュアーのコメントに応じてコードを見直すと思います。 見直しが終われば、 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)のリストを表示できます。

Reviewing code by others

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 への参照を除去できます。

Submit the change after the review

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のいずれかをしておく必要があります。

(既に、別のGoogleのオープンソースプロジェクトで実施している場合は、再度同意する必要はありません。)

この面倒な手続きは、初めてのコミットにだけ必要です。

標準の著作表示のヘッダは、以下を使うようにしてください:

// 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