Revision as of 11:36, 29 June 2012

Gerrit ワークフロー　クイックリファレンス

このセクションは新しいリポジトリで作業を始める為に必要なコマンドの クイックリファレンスとして意図されています。使用中のワークフローを 理解する為にこの文書全体を読んで、あなたが新しい OpenStack プロジェ クト上で作業を開始する必要がある時、このセクションを参照して下さい。

セットアップのより完全な説明は、GerritJenkinsGithub を参照して下さい。

<<TableOfContents()>>

アカウントのセットアップ

Launchpad アカウントを作成し、 Launchpad に ssh 公開鍵をアップロードしておいて下さい。

https://review.openstack.org/ を開いて、 ページの右上にある Sign In のリンクをクリックして下さい。 あなたの Launchpad ID でログインして下さい。

Gerrit は Launchpad の OpenID でのシングルサインオンを使っているので、 Gerrit 用に別のパスワードは不要です。 Launchpad, Gerrit, Jenkins のいずれかで一度ログインすれば、 他でパスワードを入力する必要はありません。

Gerrit アカウントは自動的に Launchpad と同期されます。 したがって、 Gerrit アカウントのユーザ名、フルネーム、メールアドレス、 SSH 鍵、所属グループは、 Launchpad と同じになっているはずです。

Launchpad の情報には他のシステムには公開されていないため、 コピーできない情報もあります。 Gerrit に初めてログインした際には、 ページの上にある Settings のリンクをクリックして、 Contact Information, SSH Public Keys, Groups が 正しい情報になっているか確認して下さい。正しくない場合は、 メールアドレスや SSH 鍵を登録して下さい。

以下のコマンドを実行して、git にメールアドレスを設定して下さい。

git config --global user.name "Firstname Lastname"
git config --global user.email "your_email@youremail.com"

git の設定は以下のコマンドで確認できます。

git config --list

Git Review インストール

私たちは、OpenStack 開発で使用されるコードレビューシステム 「Gerrit」を使った作業の詳細全てを扱う git のサブコマンドである 「git-review」ツールの使用をお勧めします。作業を開始する前に、あな たのシステムに git-review がインストールされている事を確認して下さ い。

Ubuntu や他のほとんどの Unix 系システムでは、以下を実行するだけです。

pip install git-review

Ubuntu Precise (12.04) 以降では、git-review はディストリビューションに含まれており、 他のパッケージと同じにようにしてインストールできます。

apt-get install git-review

Fedora 16 以降では、git-review はディストリビューションに含まれており、 他のパッケージと同じにようにしてインストールできます。

yum install git-review

Fedora 15 以前や Red Hat Enterprise Linux では、最初に pip をインストールする必要があります (パッケージ名は `python-pip` です)。その後、従来通り pip を使って git-review をインストールします。

git-review による gerrit との全てのやりとりは、通常の git コマンド のシーケンスです。ここで何が行われているかをもっと知りたい場合 は、-v をオプションに付けて下さい。実行中のコマンド全てが表示され るようになります。

プロジェクトのセットアップ

通常の方法でプロジェクトを複製します。例：

git clone git://github.com/openstack/nova.git

この時点で Gerrit について知るために、あなたのプロジェクトを設定す るようgit-review に依頼したいかも知れません(そうでないとしても、最 初にレビューの為に変更をサブミットする際にはこのようになります)。 この為には(もう一度、Nova を例に取ると):

cd nova
git review -s

git-review は、あなたの ssh キーであなたが gerrit にログイン出来る ことをチェックします。本コマンドは あなたの gerrit/launchpad ユーザ 名が現在実行中のユーザと同じであると仮定しています。もし(ssh キー が)機能しない場合、本コマンドはあなたに gerrit/launchpad ユーザ名 を問い合わせるでしょう。

プロジェクトのディレクトリには、隠しディレクトリ `.git` と隠しファイル `.gitreview` があります。 次のコマンドで確認できます。

ls -la

通常のワークフロー

一度あなたのローカルリポジトリが上記のようにセットアップされたら、 以下のワークフローを使用しなければなりません。

アップストリームの最新の変更が反映されている事を確認します。

git remote update
git checkout master
git pull origin master

あなたの作業を保持する為の トピックブランチを作成し、そ こに切り替えます。 もしあなたがブループリント(機能案)上で作業している場合、あなたのト ピックブランチ名をbp/BLUEPRINTにして下さい(BLUEPRINT の部分 は launchpad 中のブループリント名、例：「bp/authentication」)。そ うでない場合、Gerrit 中であなたの変更がトピックとして表示されるの で、意味のある名前を付けて下さい。

git checkout -b TOPIC-BRANCH

変更のコミット

git のコミットメッセージは短い 50 文字以下の単一段落の概要で始まる 必要があります。その下の段落はより詳細な変更を説明すべきです。

もしあなたの変更があるブループリントまたはバグを参照している場合、 以下の書式を使用してコミットメッセージ中でそれらに言及する事を忘れ ないで下さい。

blueprint BLUEPRINT
bug #######

例：

Adds keystone support.

Implements blueprint authentication.  Fixes bug 123456.

(Long description of the change).

変更を作成し、コミットして、レビューの為にサブミットして下さい。

git commit -a
git review

#!wiki caution
'''注意'''

あなたのマスターブランチに変更をチェックインしないで下さい。これを
やってしまうと、新しいアップストリームの変更を pull する際、マージ
コミット(merge commits)を引き起こしてしまい、マージコミットが
Gerrit によって受け入れ(accept)られなくなります。

チェックインの前に「./run_tests.sh -p」を実行する事を忘れないで下
さい。

Review

Once the code is committed, it appears at https://review.openstack.org. Please refer http://wiki.openstack.org/GerritJenkinsGithub for more information. If the link corresponding to your code is clicked, it will show the status and other information. Automatic testing will be done and the results will be displayed once they are complete. Reviewers will come and review and leave comments in the comment box or in the code itself.

If there is an in-line comment, you can see it from expanded "Patch Set." "Comments" column will show how many comments are in each file. If you click a file name that has comments, the new page will show a diff page with the reviewer's name and comments. Click "Reply" and write your response. It will be saved as a draft if you click "Save." Now, go back to the page that shows a list of patch sets and click "Review," and then, click "Publish comments."

If your code is not ready for review, click "Work in Progress" to indicate that a reviewer does not need to review it for now. Note that the button is invisible until you login the site.

Drafts

A change can be submitted as a draft if, for example, it's not ready for merging, or even general code review, but you would like to share it selectively to get early comments. If you upload a change as a draft, by default, no one else can see it. You must explicitly add each person you would like to share it with as a reviewer. Reviewers you add can leave comments, but cannot vote at this stage. You can continue to upload new patchsets to the change as it evolves, and once it is ready for general review, you can click the "Publish" button. It will then become a normal change in Gerrit that everyone can see, including the earlier reviews from the draft stage. This is a one way transition; once a draft is published, it can't be made a draft again.

A draft change is uploaded by adding the "-D" option. Simply make changes, commit them, and submit them as a draft:

git commit -a
git review -D

#!wiki caution
'''Note:'''

Earlier versions (prior to 1.16) of git-review may also have the "-D" option, but the git ref that Gerrit uses to indicate a change should be a draft was changed; so if using "-D" results in an error, you may need to upgrade to latest.

長寿のトピックブランチ

あなたがより大きなプロジェクトで作業をしている場合、あなたは暫くの 間あなたのトピックブランチで作業をしたいかも知れません。この場合、 あなたは

開発中にあなたの変更をしばしばチェックインし、コードレビューの為に サブミットする前にあなたの変更をマスターリポジトリの最新状態をベー スにする(rebase)必要があるかも知れません。

あなたが作業を開始してからマスターリポジトリが変更された場合、あな たはあなたの変更を最新の状態にリベースすべきです。そして、あなたが 細かなコミットを多数行った場合、あなたはそれらを１まとめにして、細 かなコミットが公式リポジトリに現れないようにすべきです。

覚えておいて下さい：各コミットは Gerrit の中で１つの変更になり、個 別に了承される必要があります。あなたがプロジェクトに対して１つの 「変更」を行った場合、表向きはあなたの多数の「チェックポイント」コ ミットは１つのコミットにまとめられます。以下がそれら両方を行う方法 です。

git checkout master
git pull origin master
git checkout TOPIC-BRANCH
git rebase -i master

エディタを使用して、公式の履歴に現れるべきではない任意のコミットを １まとめにします。もしあなたがたった１つの変更を Gerrit にサブミッ トしたい場合、あなたはこのプロセスの最後に１つの「pick」行を書くだ けとなります。完了後、あなたはエディタで公式のコミットメッセージを 用意する事が出来るようになります。あなたは pick したコミットからコ ミットメッセージを書き始める事が出来、そしてメッセージには Change-Id 行が含まれるべきです。編集時にメッセージに Change-Id 行 を残すことを忘れないで下さい。

一度、あなたのブランチ中のコミット履歴が正しいようであれば、「git review」を実行してあなたの変更を Gerrit にサブミットして下さい。

変更の更新

コードレビュープロセスが追加の変更を提案する場合、それらの変更を行っ て既存のコミットを修正(ammend)して下さい。コミットメッセージ中の既 存の Change-Id: フッターをそのまま残すと、Gerrit はそれが既存の変 更に対する更新パッチとして扱います。

git commit -a --amend
git review