はじめての OpenStack コントリビューション

はじめて OpenStack のコントリビューションを行う方を対象として
各種アカウントの作成から Sandboxリポジトリを使ったレビューのテストまでを説明していきたいと思います。

# コントリビューションを行うメリット
コントリビューションを行うメリットとして、以下のようなことが挙げられます。

- 直近の2つのリリースサイクル中に一度でもコアプロジェクトにコントリビューションすると、ATC（Active Technical Contributer）となることができ、以下の特典を受けることができる。
  - Technical Commitee menberの選挙の投票権を持ち、デザインサミットを初めとするプロジェクトのミーティングに招待される。
  - 半年毎に開催されるOpenStack Summitに無料で参加できる。
- ローカルで行ったバグ修正を適用したり、自分の欲しい機能を提言・実装することが可能になる。
- OpenStack の内部実装についての知見が蓄積されることにより、顧客に合わせた開発も可能となる。
- 企業としてコントリビューションを行った場合、企業のブランディングとして活用できる。

# コミュニケーションツール
公式に提供されているコミュニケーションツールについても紹介しておきたいと思います。

- [Launchpad](https://launchpad.net/openstack)
こちらで、Blueprint やバグが管理されています。
ユーザーは、こちらから対応する Buleprint やバグを選び、対応していきます。
慣れないうちは「low-hanging-fruit」とタグ付けされているものから始めるのがよさそうです。

- [Gerrit Review](https://review.openstack.org/)
提出されたコードに対してのコードレビューやコメント等が行われます。

- [IRC](https://wiki.openstack.org/wiki/IRC)
IRC では、議論やレビュー依頼等が行われています。
__※[こちら](http://eavesdrop.openstack.org/irclogs/)から IRC Log を見ることができます。__

- [メーリングリスト](http://lists.openstack.org/cgi-bin/mailman/listinfo)
様々な情報のやり取りがおこなわれています。

# 実施手順
## アカウントのセットアップ
### Launchpad
Launchpad は、 OpenStack コミュニティーがバグ報告などを記録するためのものです。
また、そのアカウントは OpenStack のコードレビューシステムで、我々を識別するためのものです。

#### サインアップ
1. [Launchpad](https://launchpad.net/) にアクセスします。
2. 「I am a new Ubuntu One user」をクリックします。
3. メールアドレス、名前、パスワードを入力し、利用規約に同意します。
![1.png](https://qiita-image-store.s3.amazonaws.com/0/129198/3812df35-c218-6f84-54f2-fdcbecacf6d0.png)

### OpenStack Foundation アカウント
OpenStack Foundation アカウントを登録することにより、以下を行うことが可能となります。

- コードのコントリビューション
- 選挙への投票
- OpenStack プロジェクトの、選挙を行うポジションへの立候補
- OpenStack カンファレンスへのプレゼンテーションの提出

#### サインアップ
__※ メールアドレスが、コードのコントリビューションに使いたいアドレスと同一であることを確認してください。__

1. [OpenStack Foundation](https://www.openstack.org/join/register/?membership-type=foundation) にアクセスする。
2. 個人メンバーの場合、「Foundation Member」ボタンを押下する。
3. 現在の個人メンバー用の規約と、我々の Community Code of Conduct に目を通し、登録を完了する。
![2.png](https://qiita-image-store.s3.amazonaws.com/0/129198/ec04c516-1dd2-268e-eace-bbe17e7c00ab.png)

### Gerrit アカウント
Gerrit は、OpenStack コミュニティで利用しているレビューシステムです。
以下のものが、Gerrit 上でレビューされています。

- コード
- スペック
- 翻訳
- 機能のユースケース

#### サインアップ
[Gerrit のページ](https://review.openstack.org/#/q/status:open) を開き、右上にある「sign in」のリンクをクリックします。

ユーザ名の選択が促されます。
（launchpad などと同じ名前を入力しても問題ありません。）
__※ Gerrit にサインインすると、 Launchpad のログイン情報の入力を促されますが、
これは Gerrit が OpenID シングルサインオンを用いるためのものです。__

### Individual Contributor License Agreement
個人やエンティティーのコントリビューションについての、知財のライセンスを明示したアグリーメント。
__※アグリーメントの全文は[こちら](https://review.openstack.org/static/cla.html)__

#### 連絡先情報の登録
連絡先情報を登録します。
[Gerrit の settings ページ](https://review.openstack.org/#/settings/)の Connect Information を開き、
「Contact information last updated on ..」の表示がない場合、
下欄に連絡先情報をに記入後、「Save Changes」で保存します。
![gerrit.png](https://qiita-image-store.s3.amazonaws.com/0/129198/0bd87070-65f2-b796-5ec8-760801f1a153.png)

#### 署名
##### 個人コントリビューターの場合
New Contributor Agreement のリンクをクリックして、同意書に署名します。
![3.png](https://qiita-image-store.s3.amazonaws.com/0/129198/3e58bf25-8b5a-9039-5ed0-86e30bc5fbd9.png)

##### 企業や組織としてコントリビューションする場合

1. New Contributor Agreement リンクをクリックして、同意書に署名します。

2. 企業や組織の従業員は Corporate Contributor License Agreement に署名する必要があります。
![3 (1).png](https://qiita-image-store.s3.amazonaws.com/0/129198/10f6f463-7591-9107-d906-b30bb0021f67.png)

```text
注: 雇用者は、Updated Schedule A Form を埋めて、署名することにより、許可された従業員の一覧を更新できます。
```

##### U.S. Government としてコントリビューションする場合
権限を持つ誰かが USG CLA(U.S. Government Contributor License Agreement) に署名をする必要があります。
処理を開始するために、 OpenStack Foundation <mailto:communitymngr@openstack.org> に連絡をしてください。

# git のセットアップ
Git は、フリーでオープンソースの分散バージョン管理システムです。
OpenStack ソースコードの変更管理に使用しています。

#### インストール
##### Mac OS

[Git のダウンロードページ](https://git-scm.com/download/) にアクセスし、「Mac OS X」をクリックします。
ダウンロードした dmg ファイルを開き、画面の指示に従いインストールしていきます。

Homebrew パッケージマネージャーを使用してインストールする場合は、以下のコマンドを実行します。

```bash
$ brew install git
```

##### Linux
debian、ubuntu などのディストリビューションの場合、以下のコマンドを実行してインストールする。

```bash
$ sudo apt-get install git
```

RHEL、CentOS などのディストリビューションの場合、以下のコマンドを実行してインストールする。

```bash
$ sudo yum install git
```

#### Git の設定
Git のインストールが完了したら、ターミナルを開き、自身の情報を登録します。

__※「FirstName」「LastMame」「EmailAddress」は、それぞれ自身の情報に置き換えてください。__

```bash
$ git config --global user.name "FirstName LastMame"
$ git config --global user.email "EmailAddress"
```

正しく登録されたかどうかは、以下のコマンドで確認できます。

```bash
$ git config --list
user.name=FirstName LastMame
user.email=EmailAddress
```

### Git Review
Git review は OpenStack コミュニティーによりメンテナンスされているツールです。
Git に次のようなサブコマンドを追加します。

- git review

OpenStack プロジェクトリポジトリーに変更を加えた際、
このサブコマンドを使うことで変更がレビューされるようになります。

#### git-review インストール
ターミナルより、以下のコマンドでインストールできます。

```bash
$ pip install git-review
```

#### 設定
Git review は、実行ユーザーが Gerrit のユーザー名と同一であると見なします。
もし異なる場合は、git config で設定して対応します。

```bash
$ git config --global gitreview.username <username>
```

お使いの Gerrit ユーザー名がわからない場合、Gerrit 設定 を確認してください。

### SSH 鍵のセットアップ
Gerrit へ push を行う際に ssh 鍵を使用して認証を行います。

#### SSH 鍵の生成
ターミナルより、ssh-keygen コマンドを使用して ssh 鍵を作成します。

```bash
$ ssh-keygen -t rsa -b 4096 -C "EmailAddress"
Generating public/private rsa key pair.
Enter file in which to save the key (/home/username/.ssh/id_rsa): # Enterキー押下
Enter passphrase (empty for no passphrase): # Enterキー押下
Enter same passphrase again: # Enterキー押下
Your identification has been saved in /home/username/.ssh/id_rsa.
Your public key has been saved in /home/username/.ssh/id_rsa.pub.
<省略>
```

公開鍵(id_rsa.pub)と秘密鍵(id_rsa)がそれぞれ作成されたことを確認します。

```bash
$ ls ~/.ssh
id_rsa  id_rsa.pub
```

#### 公開鍵のコピー
##### Mac OS & Linux

ターミナルから次のコマンドを実行し、表示された公開鍵のテキストをクリップボードにコピーします。

```bash
$ cat ~/.ssh/id_rsa.pub
```

#### Public Key の Gerrit へのインポート
[Gerrit の SSH 公開鍵の設定ページ](https://review.openstack.org/#/settings/ssh-keys)にアクセスします。

「Add Key ...」ボタンをクリックします。

Add SSH Public Key テキストボックスに公開鍵をペーストし、「Add」ボタンを押下します。

## 動作確認(sandbox)
sandbox を使ってレビューまでの流れをテストします。
sandbox は練習用のサイトなので、何をしても問題ないです。

- sandbox のソースコードをクローンして移動します。

```bash
$ git clone http://git.openstack.org/openstack-dev/sandbox
$ cd sandbox
```

- git review のためのセットアップを行います。

```bash
$ git review -s
Creating a git remote called "gerrit" that maps to:
        ssh://username@review.openstack.org:29418/openstack-dev/sandbox.git
```

- 作業用に新しくブランチを作成します。
  * blueprint対応の場合、"bp/<[launchpad](https://launchpad.net/openstack) のブループリント名>"
  * バグ対応の場合、"bug/<[launchpad](https://launchpad.net/openstack) のバグ番号>"

```bash
$ git checkout -b bp/hello
Switched to a new branch 'bp/hello'
```

- ファイルを変更します。

```bash
$ vi hello.py

$ git diff
diff --git a/hello.py b/hello.py
index 6be1994..70d5a40 100644
--- a/hello.py
+++ b/hello.py
@@ -1,5 +1,6 @@
 def main():
-       print "Hello World"
+       print "Hello"
+       print "World"

 if __name__ == '__main__':
        main()
```

- git add して commit します。

```bash
$ git status
On branch bp/hello
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   hello.py

no changes added to commit (use "git add" and/or "git commit -a")

$ git add .

$ git status
On branch bp/hello
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

        modified:   hello.py

$ git commit -F- <<EOM
> Commit Test
>
> This is a commit test.
>
> * change message
> EOM
[bp/hello b1654e2] Commit Test
 1 file changed, 2 insertions(+), 1 deletion(-)

$ git log
commit b1654e20b34010b2fcf2835ac13122f654b92e67
Author: username <EmailAddress>
Date:   Fri Jul 15 21:40:08 2016 +0900

    Commit Test

    This is a commit test.

    * change message

    Change-Id: I7cee171c5d34799b05ba912ae24058fee2724e32
```


- `git review`コマンドでレビュー依頼を出します。
```
$ git review
remote: Processing changes: new: 1, refs: 1, done
remote:
remote: New Changes:
remote:   https://review.openstack.org/343982 Commit Test
remote:
To ssh://otsuka@review.openstack.org:29418/openstack-dev/sandbox.git
 * [new branch]      HEAD -> refs/publish/master/bp/hello
```

- [gerrit のページ](https://review.openstack.org/)を開き、ログインすれば、[My]-[Changes] より、
レビュー依頼した内容を確認することができます。


- コードレビューを想定し、以下の操作を行います。
画面上部の「Reply...」ボタンを押下後、メッセージ、Code-Review のポイントを設定し、「Post」ボタンを押下します。
Review のポイントについては、通常の Reviewer が +1、Core Reviewer が +2の評価点を付けることができます。

- 画面上部の「Workflow+1」ボタンを押下します。
以下の条件を満たされている場合、コードがマージされます。

* Review の評価点 +2 が 2つ以上
* Jenkins のテストが正常終了
* Workflow +1 以上

===============================================================

# 参考資料
アカウントのセットアップ
- http://docs.openstack.org/ja/upstream-training/accounts.html

Git のセットアップと学習
- http://docs.openstack.org/ja/upstream-training/git.html

Upstream Traning 資料
- http://docs.openstack.org/ja/upstream-training/

OpenStack公式Gitリポジトリー
- https://git.openstack.org/

OpenStack流のGitコミットメッセージの書き方
- https://wiki.openstack.org/wiki/GitCommitMessages

Developer’s Guide
- http://docs.openstack.org/infra/manual/developers.html

Core Reviewer’s Guide
- http://docs.openstack.org/infra/manual/core.html