はじめまして。@kazshinoharaです。
この記事は NTTコミュニケーションズ Advent Calendar 2017 の5日目です。
はじめに
弊社ではOpenStackを活用したクラウドサービス[1]を提供していまして、私はHeat[2]を使ったオーケストレーションサービスの開発を担当しています。
2016年の9月頃からHeatをぼちぼち弄りはじめました。開発の過程でHeatのテンプレート[3]をDrag&Dropでユーザーに簡単に作成してもらえるHorizon[4]のpluginをチームで作りました。最初は弊社クラウドサービスでのみ使っていた俺俺pluginだったのですが各所で評判が良かったので、OpenStack自体にContribution(コード提供)出来ないかなぁと思ったのがキッカケでOpenStackのUpstream活動をはじめました。
[1] https://ecl.ntt.com/documents/
[2] https://wiki.openstack.org/wiki/Heat
[3] https://docs.openstack.org/heat/pike/template_guide/hot_guide.html
[4] https://wiki.openstack.org/wiki/Horizon
本記事では「OpenStackで新しいプロジェクトを立ち上げ」るまでのステップを以下2つのパートに分けて書きたいと思います。抜け漏れ誤りあったらご指摘頂けると嬉しいです。
- Upstream Contributorになる編
- 実際にOpenStackにパッチを投げたりするところまでの話
- 実際のプロジェクトを立ち上げる編
- OpenStackに新しいプロジェクトを作ったときにやったこと
Upstream Contributorになる編
いきなり自分達で書いたPluginをまるっとOpenStack本家にマージしてもらえるとはさすがに思えなかったので、はじめは正攻法で小さなパッチを投げてるみることにしました。※gitとかの操作は出来るもんだという前提で話を進めます
環境の準備
1. OpenStack Foundationのアカウントの作成
https://www.openstack.org/join/
Community MemberとFoundation Memberの2種類がありますがCode Contributionする場合はFoundation Memberが良いみたいです。(私もそうしてます）
余談ですが年に2回行われるOpenStack SummitのSpeaker応募をする場合もこのOpenStack Foundationのアカウントが必要です。
2. Ubuntu Oneアカウントの作成
https://login.ubuntu.com
OpenStack関係のツールはいくつかありますが基本このアカウントでSSO出来ます。
3. Launchpadへのサインイン
https://launchpad.net/
バグやブループリント(追加機能要望)の管理を行うところです。
前述のSSOアカウントでサインイン出来ます。
4. Gerritへのサインインと設定
https://review.openstack.org/
Gerritは提出したパッチのレビューなどを行うところです。
前述のSSOアカウントでサインイン出来ます。
画面右上の自分のアカウント名からプルダウンでSettings→Agreementsを選択、Agreement typeはICLA(Individual Contributor License Agreement)を選択しメニューに従って進めます。※企業単位でContributionを行う場合はCCLAを選択するようです。
Agreementsの設定が終わったら、Contact InformationとSSH Public Keysを設定します。Contact informationのEmailアドレスは後ほどパッチを提出する際に使うgit userのEmailアドレスと一致している必要があります。またSSH Public Keysも同様で実際にパッチをgit ***する環境のものを登録しないといけません。お気をつけて。
5. git-reviewインストール
パッチが出来たらgit-reviewコマンドを使ってgerritに提出します。
ローカルにそのための環境を作っておきましょう。
私はpyenvを使ってるのでこんな感じで。
$ pyenv virtualenv 2.7.11 os-upstream
$ pyenv local os-upstream
$ pip install git-review
$ pip freeze
certifi==2017.11.5
chardet==3.0.4
git-review==1.26.0
idna==2.6
requests==2.18.4
urllib3==1.22
ついでにローカルのgit configを確認しておきましょう。
特にEmailアドレスがgerritに登録されたものと同じか要チェックです。
$ git config --list
パッチを投げてみよう
1. バグ探し
ここまで準備出来たらパッチを投げることが可能です。
Launchpadに行ってとりま自分でも直せそうなものを選びましょう。
OpenStackのプロジェクトごとにLaunchpadのプロジェクトが存在しているのでお好きなプロジェクトでどうぞ。
人それぞれだと思いますが私は一番馴染みのあったHeatにパッチを投げたのでそれを参考に説明します。
https://bugs.launchpad.net/heat
上記URLにアクセスするとバグが一覧で表示されます、各バグにはプライオリティやステータス、担当者(Assigned to)が設定出来るようになっています。バグの詳細はそのバグをレポートした人によってBug Descriptionとして記載されています。自分で直せそうだなと思ったらAssigned toがUnassigned(誰も担当者がいない)であることを確認して自分の名前を入れてみましょう。これでこのバグは自分が直しますと宣言したことになります。ものによっては何のこと言ってるのか分からないものも多々あると思うので最初は簡単なものを探しましょう。おすすめはドキュメントバグです。
2. パッチ作成とレビューリクエスト
ここからは私が最初に投げたパッチを参考に説明します。
https://bugs.launchpad.net/heat/+bug/1689026
ステータスは既にリリース済みなのでFix Releasedになっています。
このバグはHeatのInstall Guideというドキュメントに誤りがあるという簡単なものでした。
とは言えHeatのレポジトリの中を弄る変更には変わりないのでパッチを投げるプロセスは他と同じです。
まず修正するコードを含むレポジトリをローカルにクローンしてきます。
ブランチはMasterのままでOKです。
$ git clone git://git.openstack.org/openstack/heat
他のプロジェクトのレポジトリは以下から探してみてください。
https://git.openstack.org/cgit
お好みのテキストエディタもしくはIDE等を使って問題箇所を修正します。
修正が終わったらクローンしてきたローカルレポジトリでgit reviewが使えることを確認します。私の場合、pyenvなので以下な感じです。
$ pwd
~/dev/openstack/heat
$ pyenv local openstack
$ git review -s
Creating a git remote called "gerrit" that maps to:
ssh://kaz_shinohara@review.openstack.org:29418/openstack/heat.git
ブランチを切ってインデックスに追加したいファイルをaddしましょう。
ブランチ名は bug/BUG_NUMBERのフォーマットとなります。
BUG_NUMBERはLaunchpad上で確認出来るものです。例えば私の例で言うと1689026となります。
$ git branch bug/BUG_NUMBER
$ git add PATH_TO_YOUR_CHAGED_FILE
次にCommitを行いますがOpenStackにはCommitメッセージのお作法[5]があるので注意してください。Reviewerにも依りますが厳しい人は厳しいです。
[5]https://wiki.openstack.org/wiki/GitCommitMessages
$ git commit
Updated the description about the verify operation #ここは50文字まで
# 1行空けて変更箇所の詳細をここに書く
Closes-Bug: #1689026 #BUG_NUMBERを書く
Change-Id: I163fadf9c8d15e4bc1632c0ae9004e76ec2079ad #自動で入る
CommitメッセージにはChange-IDが入っている必要があります。git-reviewによって自動的に追加されます。一度Commitした後に以下を実行しておきましょう。Chnage-IDがCommitメッセージに追加されるはずです。
$ git commit --amend
ここまで来たらパッチをGerritに投げます。
以下な感じでコマンドが終了したら成功です。
$ git review
remote: Processing changes: new: 1, refs: 1, done
remote:
remote: New Changes:
remote: https://review.openstack.org/463154/ Updated the description about the verify operation.
remote:
To ssh://review.openstack.org:463154/openstack/heat.git
* [new branch] HEAD -> refs/publish/master
開発に関わる詳細は公式のDeveloper's Guide[6]を見てみてください。
OpenStackでは各プロジェクト毎にCore Reviewerと言われる人たちがいます。
この人達にレビューを受けて承認されるまでパッチがMasterブランチにマージされることはありません。パッチがレビューを受けるまで待ちましょう。レビューの結果、更に修正を求められるかもしれません、そこは真摯に対応しましょう。原則2人のCore Reviewerから承認(gerrit上で+2を2回もらう)されればパッチはGateと呼ばれるworkflowを通じてMasterブランチにマージされます。一連の流れは以下の図が分かりやすくなってます。
[6]https://docs.openstack.org/infra/manual/developers.html
コミュニケーション
パッチを投げたはいいが中々レビューされないことが多いと思います、特に大きなプロジェクトになるとパッチの数も膨大でCore Reviewerの人たちも忙しいです。私のパッチ見てよーっと直接お願いしたいところです。OpenStack Communityの開発者同士で連絡を取る方法は主に以下2つの方法があります。
- IRC
- リアルタイムで話をしたい場合、IRCを使うことになります。各プロジェクト毎にチャンネルがあるのでそこで問い合わせをしたり、レビューの依頼をしたりします。また大抵各プロジェクト毎に週に1度IRC上で定例ミーティングを行っているのでそこに顔を出してみるのも良いと思います。
- ML
- 開発者であればopenstack-devには入っておいた方がよいです。
- http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
- 結構たくさんメールが飛び交うのでsubjectに[openstack-dev][heat]みたいな感じでtopicが指定されてるのでこれでフィルターを作っておくと楽です。
- 開発者であればopenstack-devには入っておいた方がよいです。
イベントへの参加
オンラインのコミュニケーションの他にもOpenStackではいくつかのイベントが定期的に開催されています、代表的なイベントが年に2回開催されているOpenStack Summitです。
ここでは様々なOpenStackとそのエコシステムに関わるセッションに加えて、各プロジェクト毎のOnboarding Sessionと言われる新規開発者向けのセッションや、Upstream Instituteというhands-on形式で実際にOpenStackにパッチを投げるまでのHow toを教えてくれるクラスも行われます。
Upstream InstituteはコンテンツをWebで公開しているので是非見てみてください。
https://docs.openstack.org/upstream-training/upstream-training-content.html
私も今年の5月にボストンで開催されたOpenStack SummitでこのUpstream InstituteとHeatのOnboarding Sessionに参加していろはを学びました。
次回は2018年5月21〜24日、カナダのバンクーバーで開催される予定です。
https://www.openstack.org/summit/vancouver-2018/
実際にプロジェクトを立ち上げる編
OpenStackにパッチを投げるところまで来ました、次は実際にプロジェクトを立ち上げるところを纏めていきます。
提案してみた
とりあえず自分たちがOpenStackに提供したい機能を前述のHeatの定例ミーティング(IRC)で話してみました。提案内容自体は普通に受け入れられて是非やろう！というレスポンスをもらいました。提案した機能は冒頭で書いたDrag&Dropのtemplate generatorですが、それに加えてHeatのCore developer達から元々Horizonで持っているHeat向けの機能も引き取ってHeat Dashboardという独立したプロジェクト(レポジトリ)にしてはどうかという話になりました。その足でHorizonの定例ミーティング(IRC)に参加し、同様の提案を行ってみました。こちらのレスポンスも上々でした。さらっと提案して受け入れられたように書いてますが、、実際は今年の5月のボストンサミット以来、細々パッチを提出したり、MLの議論に参加したり、週に1度のIRCによる定例ミィーティング(毎週木曜日0時開始)にほぼ皆勤で出席したり地道な活動をしてきたのである程度プレゼンスがある状態でした。(いわゆるwho are you ?的な感じではない)
PTGへの参加
IRC上にミーティングでHeatとHorizonチームそれぞれと会話をして今後の方針みたいのは纏まりました。OpenStackではProject Team Gathering(PTG)[7]という開発者向けのイベントを開催していて、ここで各プロジェクトの開発者たちが一堂に介し今後の開発項目やバグのトリアジなど議論を行っています。今年の9月に米国のデンバーでPTGが開催され我々も提案内容の詳細を詰めるために現地に行ってきました。ここではHorizonとHeatのそれぞれのデベロッパーとどうやってHorizonからHeat向けコードを分離させるか、template generatorに実装されるべき機能などFace to FaceでHorizon及びHeatの開発者と議論を行い、Heat Dashboardという新たなプロジェクト(レポジトリ)を作ることで合意形成を行いました。
[7]https://www.openstack.org/ptg/
実際のプロジェクト作成
PTG後、実際のプロジェクト作成過程に入りました。
基本的な手順は以下のドキュメントの通りなのですが、、
https://docs.openstack.org/infra/manual/creators.html
それじゃ味気ないのでポイントを以下に纏めます。
1. Launchpadの設定
バグとかブループリントの管理が出来るように https://launchpad.net に新しいプロジェクトを追加します。
2. PyPIの設定
開発した新しいプロジェクトのパッケージ(Pythonコード)をpipでインストール出来るようにするために、PyPIに器を用意します。PyPIのアカウントを持っていない人は作りましょう。パッケージの名前はレポジトリの名前と一緒にしてPKG-INFOのversionは0にしておきましょう。
3. Project Configの設定
新しいプロジェクトをOpenStackのCI Systemに追加します。
設定は全てopenstack-infra/project-configというレポジトリで管理されているので実際の設定はこのレポジトリに対してパッチを投げるかたちとなります。
色々設定があるのですが代表的なところでzuul.d/projects.yamlがあります。
ここではgerritに飛んだパッチに対するテストやレビュー後のMasterブランチへのマージ等々のworkflowの設定を行います。
私のケースでは以下な感じです。
- project:
name: openstack/heat-dashboard
templates:
- system-required
- check-requirements
- publish-openstack-sphinx-docs-horizon
- openstack-python-jobs-horizon
- openstack-python35-jobs-horizon
- nodejs4-jobs
- release-notes-jobs
- publish-to-pypi-horizon
また特定のIRCチャンネルにイベント毎(パッチの提出等々)に通知を飛ばしたりする設定もここで行われます。
前述のバグの対応と同様、ローカルに当該レポジトリをクローンしてきて作業しましょう。
git clone git://git.openstack.org/openstack-infra/project-config
ちなみに私のパッチはこれです。
これからプロジェクトを立ち上げる方は参考にしてみてください。
https://review.openstack.org/#/c/509119/
4. Governanceレポジトリへの追加
新しく作成するプロジェクトがOpenStackの公式レポジトリとして扱われるためにはopenstack/governanceというレポジトリにエントリーされている必要があります。
git clone http://git.openstack.org/cgit/openstack/governance
reference/project.yamlに新しいプロジェクトを追加しましょう。
私の場合Heat DashboardがHeatのサブプロジェクトという位置付けだったのでこんな感じでした。
heat:
ptl:
name: Rico Lin
irc: ricolin
email: rico.lin.guanyu@gmail.com
irc-channel: heat
service: Orchestration service
mission: >
To orchestrate composite cloud applications using a declarative
template format through an OpenStack-native REST API.
url: https://wiki.openstack.org/wiki/Heat
deliverables:
heat:
repos:
- openstack/heat
docs:
contributor: https://docs.openstack.org/heat/latest/
api: https://developer.openstack.org/api-ref/orchestration/
tags:
- tc:approved-release
- vulnerability:managed
- assert:follows-standard-deprecation
- assert:supports-upgrade
- stable:follows-policy
略)
heat-dashboard: #このセクションを追加
repos:
- openstack/heat-dashboard
ちなみに私のパッチはこれです。
https://review.openstack.org/#/c/504166/
5. その後
openstack-infra/project-configとoepnstack/governanceへの両パッチがレビューされマージされるとOpenStack Infra teamが新しいプロジェクト用にレポジトリを作成してくれます。
PTGなどで合意形成をちゃんとしておけば問題なく承認されるはず。です。。
本当はリリースのところまで書きたいのですが今現在その対応している最中なので残りは別の機会に書きます。
終わりに
自分の備忘録がてら書きました。誰かの何かの参考になれば幸いです。
実際に立ち上げたHeat Dashboardプロジェクトについては記事[8]で紹介しているので興味があれば読んでみてください。DevStackでの利用方法やデモ動画へのリンクを掲載しています。
OpenStackをやってていいなぁと思うのが開発者コミュニティがとてもオープンでフレンドリーなところです。ここまでくるのにたくさんの人に助けてもらいました。心から感謝していますし、私もお世話になった分を逆にコミュニティに還元していきたいなぁと思ってます。
