#300 Contributing to Open Source

Githubによって、オープンソースプロジェクトへの貢献がかつては信じられなかったほど簡単になりました。今回のエピソードでは、オープンソースへ貢献する具体的な方法を、VCR projectにpull requestを送信する手順を例にして紹介します。このgemは、テストをスピードアップするためにHTTPによる通信を記録して再生する手段を提供するもので、エピソード291で取り上げました。gemの作者のMyron Marstonは他の人からの貢献に対して迅速に対応しています。

例えばこのgemに問題を発見したとして、パッチを提供して貢献したいとします。まずやるべきことはgemのissue tracker(問題追跡リスト)を見て、すでに過去に報告されていないかどうかを確認します。もしそのプロジェクトにメーリングリストがあれば、見つけた問題に関連する項目がないか探すのもいいでしょう。大きな変更をおこなう場合は、まずその変更が本当に必要かどうかを議論するのがいいでしょう。

forkする

修正をおこなうとなったら、まず最初にプロジェクトをforkします。このためにはまずプロジェクトのホームページにアクセスして「fork」ボタンをクリックします。数秒で自分用のリポジトリのコピーが作成されるので、新しいforkのページに移ってcloneするためのURLを取得します。

$ git clone git@github.com:eifion/vcr.git
$ cd vcr

リポジトリをcloneしたら、どんなブランチがあるかを確認します。

$ git branch -r
  origin/1-x-stable
  origin/HEAD -> origin/master
  origin/jruby_nailgun
  origin/master

ここでわかるのは、安定版であるバージョン1のブランチがあり、これがこのgemの最新版だということです。マスターブランチはバージョン2を指していて、現在はプレリリース版です。今自分が使っているgemのバージョンが今見ているコードのバージョンとは違うかもしれないということに常に気をつけるようにしてください。

プロジェクトの開発環境を設定するときには、ドキュメントをチェックすることが大事です。今回のケースではREADMEファイルにdevelopmentセクションがあり、そこにはpull requestは歓迎とありますが、修正箇所はすべてテストされていなくてはいけないとあります。READMEにはgemのテストスイートの実行方法については何も指示がありませんが、心強いことにTravis CIによるとテストは現状すべて成功しているとあります。

プロジェクトにはGemfileがあり、Bundlerで依存関係を管理しています。bundle installを実行することでインストールできるはずですが、これを試してみるとエラーが発生します。すべてのシステムは構成が違っているため、これは予想されることです。プロジェクトを自分の環境に導入しようとしたら不具合の一つや二つにはひっかかるものだと考えておく方がいいでしょう。

表示されているエラーはrb-fsevent gemの関連で、検索してみるとこの問題は設定環境に関連しているようです。OS XでフルのXcodeインストールではなくGCCインストーラを使っていますが、現在のバージョンではこの方法ではインストールできません。この問題は最新のrb-fseventでは修正されていますが、安定版にはまだ修正はおこなわれていません。これを解決するにはGemfileのrb-fseventのバージョンを最新のプレリリース版に設定します。

# Additional gems that are useful, but not required for development.
group :extras do
  gem 'guard-rspec'
  gem 'growl'
  gem 'relish', '~> 0.5.0'
  gem 'fuubar'
  gem 'fuubar-cucumber'

  platforms :mri do
    gem 'rcov'
    gem 'rb-fsevent', '0.9.0.pre4'
  end

  platforms :mri_18, :jruby do
    gem 'ruby-debug'
  end

  platforms :mri_19 do
    gem 'ruby-debug19'
  end unless RUBY_VERSION == '1.9.3'
end

bundleコマンドを実行すると、すべては正常にインストールされます。

テストを実行する

次にgemのテストを実行します。これはデフォルトのRakeタスクとして設定されていることが多いので、rakeコマンドで実行できるはずです。しかし、明示的にBundlerを使用するようbundle exec rakeを実行します。

$ bundle exec rake
  1504/1504:   100% |==========================================| ETA:  00:00:00

テストはいくつかの保留された問題を除いて成功したとありますが、これは問題ありません。テストの実行後、Cucumberのシナリオが実行されます。1件の失敗があり長いエラーメッセージが表示されますが、その要点は“no such file to load -- spec"とあります。Bundlerが設定しなかったものに対する依存関係が足りないようです。

調べてみると、このプロジェクトはGit submodulesを使用しているため、正常に動かすためには次の2つのコマンドを実行します。

$ git submodule init
$ git submodule update

これらによって、サブモジュールのリポジトリがコピーされます。ここで再度テストを実行してみると、今度は成功します。

変更を加える

テストをおこなう上でいくつかの問題が発生しましたが、ついに成功させることができました。個々の開発環境は異なるため、これは予想されたことです。プロジェクトの設定方法についてさらによくドキュメント化されていれば、いくらか時間を節約できたかも知れません。そこで我々の最初のpull requestは、開発環境を設定するために必要な改良されたドキュメントをREADMEファイルに追加することにします。

すでにVCRプロジェクト専用のwikiページがあるようですが、環境設定については基本的な記述しか含まれていません。このページを編集して、経験した問題に基づいたより詳しい情報を追加します。修正を終えたら、READMEにこの貢献の仕方の案内へのリンクを追加したpull requestを送信します。

コードを変更する前に、作業をおこなったディレクトリがクリーンであることを確認します。

$ git status
# On branch master
# 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:   Gemfile
#
no changes added to commit (use "git add" and/or "git commit -a")

Gemfileを修正したので、先に進む前にこの変更を取り消します。

$ git checkout .
noonoo:vcr eifion$ git status
# On branch master
nothing to commit (working directory clean)

pull requestをおこなうごとに個別のGitブランチを立てる方がいいので、そのようにします。

$ git checkout -b readme-contributing-link

これで変更をおこなえます。README.mdのdevelopmentセクションに変更したwikiページへのリンクを追加します。

## Development

* Source hosted on [GitHub](http://github.com/myronmarston/vcr).
* Direct questions and discussions to the [mailing list](http://groups.google.com/group/vcr-ruby).
* Report issues on [GitHub Issues](http://github.com/myronmarston/vcr/issues).
* Pull requests are very welcome! Please include spec and/or feature coverage for every patch,
  and create a topic branch for every separate change you make.
* See the [Contributing](https://github.com/myronmarston/vcr/blob/master/CONTRIBUTING.md)
  guide for instructions on running the specs and features.

修正をおこなったら、git diffを実行して変更点を確認することができます。問題がなければ、コミットするために次のコマンドを実行します。

$ git commit -a -m "adding contributing link to readme."Next we need to push our branch to our remote repository.
$ git push origin readme-contributing-link
Counting objects: 5, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 328 bytes, done.
Total 3 (delta 2), reused 0 (delta 0)
To git@github.com:eifion/vcr.git
 * [new branch]      readme-contributing-link -> readme-contributing-link

これによってGithubリポジトリにブランチが追加されます。

Githubのforkされたリポジトリにアクセスしたら、現在のブランチを今追加したブランチに変更します。

次に「Pull Request」をクリックして元の所有者にpull requestを送信します。フォームにおこなった変更の内容を記入してリクエストを送ります。

Githubのオープンソースプロジェクトに対してpull requestを送信する手順は以上です。もしリクエストが取り入れられれば、その変更によって、貢献したいと思っている次の人を助けることになるでしょう。さあ次はあなたの番です。