OSS ？コントリビュート？興味無いんだけど？
という方はこちらをどうぞ！
参考：意外ととっつきやすい OSS 開発参加方法まとめ-shunsuke227ono
どうやってコントリビュートする?
ドキュメントやリファレンスを GitHub で管理している OSS(オープンソースソフトウェア)があります。
例えば、PHP の Web アプリケーションフレームワークである CakePHP の公式リファレンス(CookBook) は、 こちら(GitHub) で各国の言語に翻訳されて管理されています。
英語で書かれている本家ドキュメントを日本語へ翻訳することでコントリビュートします。
エンジニアリング感はあまり無いですが、これをやることで下記メリットを得られるのではないかと思います。
- 英語の勉強になる
- 実際のプルリクエストのフローを体感できる
- GitHub の理解度が高まる
- 頑張ればコミッターになれる(かも?)
(参考：Qiita - CakePHP3公式ドキュメントの翻訳が一石N鳥だった件
目次
この流れでいきます。各分野の理解度にもよりますが、
英語の翻訳に自信があれば１日で十分コントリビュート可能です。
- コントリビュートする OSS の決定
- OSS のコントリビュート方法の確認
- 環境を構築(Docker or Vagrant)
- 翻訳
- ビルドチェック(TravisCI)
- ビルド結果が問題なければプルリクエストを作成・送信
- マージされる
それでは早速やっていきましょう。
1. コントリビュートする OSS の決定
今回、コントリビュートする OSS は、先ほどご紹介した「CakePHP」 です。
2. OSS のコントリビュート方法の確認
CakePHP のメインのリポジトリは、こちらです。
https://github.com/cakephp/cakephp
画面を下へスクロールして README.md を読み進めるとコントリビュートする方法が書かれています。
Contributing
CONTRIBUTING.md - Quick pointers for contributing to the CakePHP project.CakePHP プロジェクトにコントリビュートするためにはこれを見てください
CookBook "Contributing" Section - Details about contributing to the project.
CookBook にもコントリビュートの詳細が書かれてる章があります。
*CONTRIVUTING.md* を見てみます。
> **How to contribute** CakePHP loves to welcome your contributions. There are several ways to help out: - Create an issue on GitHub, if you have found a bug - Write test cases for open bug issues - Write patches for open bug/feature issues, preferably with test cases included - **Contribute to the [documentation](https://github.com/cakephp/docs)**
コントリビュートの方法が書いてあります。 今回の目的はリファレンスの翻訳ですので、 一番下の行の「*ドキュメントへコントリビュートする*」のリンク先をみます。
こちらが CookBook (公式リファレンス)のリポジトリです。
README.mdを見てみます。
CakePHP Documentation
License Build Status
This is the official documentation for the CakePHP project. It is available online in HTML, PDF and EPUB formats at http://book.cakephp.org.
This master branch is the documentation for CakePHP 2.x. For CakePHP 3.x please see the 3.0 branch.
Contributing to the documentation is pretty simple. Please read the documentation on contributing to the documentation over on the cookbook for help. You can read all of the documentation within as its just in plain text files, marked up with ReST text formatting.
There are two ways for building the documentation: with Docker, or by installing the packages directly on your OS.
Build the Documentation with Docker
<br>
適当に雰囲気を読み解くと...
> - *これは CakePHPの公式ドキュメント*
- *master ブランチは CakePHP 2.x のものだから、CakePHP3.x は3.0ブランチを見てください*
- *コントリビュートする方法は2種類ある。ひとつは Docker を使ってドキュメントをビルドする方法です*
<br>
## 3. 開発環境を構築(Docker or Vagrant)
翻訳作業をする環境を構築します。
CakePHP のドキュメントは [Sphinx](http://docs.sphinx-users.jp/) で構成されています。
Docker でコンテナを作ってビルドするのが推奨みたいですが、Sphinx をビルドさえ出来ればいいので、
今回は **vagrant** と **virtualbox** を使って **sphinx** が使える **Ubuntu環境** を 作ります。
vagrantとvirtual-boxに関してはこちらをご参考ください:arrow_down:
※だいたいの雰囲気がわかったら "vagrant up"する前に戻ってきてください
:relieved: sphinxの記法については知らなくても大丈夫です。
参考：[Vagrant+VirtualBoxでUbuntu環境構築](http://qiita.com/w2-yamaguchi/items/191830191f8af05ac4dd)
参考：[VagrantとDockerについて名前しか知らなかったので試した](http://qiita.com/hidekuro/items/fc12344d36d996198e96)
<br>
上のリンクを参考に、"vagrant up" を実行出来る環境になったら
Sphinxビルド用の Vagrantfile(設定ファイル)を[こちら](https://github.com/iKenji/vagrant-sphinx)に用意して頂きましたので
"git clone" もしくは右上のボタンから"Download ZIP"してください。
:blush: ディレクトリ名は何でも大丈夫です!!
ディレクトリの準備ができたら、*Vagrantfile* と *provision.sh* があるディレクトリで **"vagrant up"** コマンドを実行します。これだけで PC内に仮想のubuntu環境ができあがります。
:relieved: vagrantって便利！
次に、ビルドする CakePHP のドキュメントを準備します
その前に...Git/GitHubがよくわからない方はこちらをどうぞ :arrow_down:
参考：[新入社員による新入社員のためのGit](http://qiita.com/shunhikita/items/9b909b566d1b0a263519)
参考：[GitHub 初心者による GitHub 入門（１）](http://qiita.com/megu_ma/items/e459e62821bdd6dbaccb)
<br>
本家 cakephp/docs リポジトリを fork して編集用のリポジトリを自分のGitHub上に作成します。
<img width="1265" alt="スクリーンショット 2016-07-18 20.06.03.png" src="https://qiita-image-store.s3.amazonaws.com/0/74133/1621f81d-9e90-99a5-1adf-f51749dd0457.png">
fork できたらローカルへ clone します。
**"vagrant up"したディレクトリ**で
```git clone git@github.com:iKenji/docs.git```コマンドを実行しましょう。
:sleeping: 鍵とかよくわからない...という方は↓
```git clone https://github.com/iKenji/docs.git```
で GitHub のID/PASSで clone できます。
※URLは画像を参考に自分のリポジトリのものを指定してください。
<img width="1210" alt="スクリーンショット 2016-07-18 20.10.02.png" src="https://qiita-image-store.s3.amazonaws.com/0/74133/a50568ae-c338-3fdd-9faf-b02b9b628424.png">
これで、本家リポジトリを fork した自分のリポジトリをローカルへもってこれました。
本家リポジトリも upstream という名前で登録しておきます。
```
$ git remote add upstream git@github.com:cakephp/docs.git
$ git remote -v (登録されたリモートリポジトリを確認)
$ origin git@github.com:iKenji/docs.git (fetch)
$ origin git@github.com:iKenji/docs.git (push)
$ upstream git@github.com:cakephp/docs.git (fetch)
$ upstream git@github.com:cakephp/docs.git (push)
```
下準備は整いましたので、
次章でビルドを行います。
Vagrantfileがあるディレクトリで"**vagrant ssh**"コマンドを実行して、
仮想マシンにSSH出来ることを確認しておいてください
## 4. 翻訳
まずは、翻訳するページを決めます。
公式リファレンス上で日本語が無いページを探します。
:open_mouth: 私は、業務上読みたいページで日本語が無い、かつボリュームが少なめページを選びました。
今回は、CakePHP3のCookieComponentのページを翻訳します。
http://book.cakephp.org/3.0/ja/controllers/components/cookie.html
GitHub上での表示は下記のようになっています。
<img width="1680" alt="スクリーンショット 2016-07-18 19.46.16.png" src="https://qiita-image-store.s3.amazonaws.com/0/74133/44877ffd-75cb-e3ed-f69f-d44b67443105.png">
### 翻訳作業をするその前に
ローカルのリポジトリを最新の状態にしておきましょう。
```
$ cd docs
$ git fetch upstream
```
今回は、CakePHP3 のドキュメントを編集するので、ブランチ3.0にチェックアウトします。
※master ブランチは現状 2.x系のドキュメントとなっています。
```
$ git checkout remotes/origin/3.0
$ git branch
* (HEAD detached at upstream/3.0)
master
```
作業する自分用のブランチを作成します。
```
$ git checkout -b translate-ja-3.0-component-cookie
$ git branch
master
* translate-ja-3.0-component-cookie
```
※ブランチ名は何をしているブランチなのかわかりやすいものにしてください。
作業用のブランチができたら、一度ビルドして編集前のHTMLを見てみましょう。
仮想マシンに SSH で接続します。
```vagrant ssh```
vagrantはデフォルトでローカルと仮想マシン(※以下VM)を、/vagrant ディレクトリでマウントしてくれます。
```
$ cd /vagrant
$ ls -la
vagrant@precise32:/vagrant$ ls -la
total 20
drwxr-xr-x 1 vagrant vagrant 306 Jul 18 10:46 .
drwxr-xr-x 23 root root 4096 Jul 18 10:32 ..
drwxr-xr-x 1 vagrant vagrant 816 Jul 18 11:25 docs
drwxr-xr-x 1 vagrant vagrant 476 Jul 18 10:46 .git
-rw-r--r-- 1 vagrant vagrant 12 Dec 12 2015 .gitignore
-rw-r--r-- 1 vagrant vagrant 216 Dec 12 2015 provision.sh
-rw-r--r-- 1 vagrant vagrant 17 Dec 12 2015 README.md
drwxr-xr-x 1 vagrant vagrant 102 Dec 12 2015 .vagrant
-rw-r--r-- 1 vagrant vagrant 3083 Jul 18 10:46 Vagrantfile
```
日本語のみビルドします。
```
$ cd docs
$ make html-ja
```
```vagrant/docs/build/html/ja ```にHTMLファイルが生成されました
ここまで来たら
1. 編集
2. ビルド
3. 確認
の繰り返しになります。
### 翻訳する
実際に編集するファイルは今回の場合
```/vagrant/docs/ja/controllers/components/cookie.rst```
になります。
sphinx の記法で翻訳していきます。
※すでに翻訳されているページや過去のバージョンを参考にします。
* 英単語の前後には半角スペースをつける
* 一行あたりの文字数
* 見出し下の # と = を十分長くする
など細かいですが気をつけましょう。
<img width="1680" alt="スクリーンショット 2016-07-18 20.39.19.png" src="https://qiita-image-store.s3.amazonaws.com/0/74133/c7ff397c-2275-6f03-8a5a-e669cb28baa0.png">
[誰でも出来る有名OSSへのコントリビュート(前編)](http://qiita.com/iKenji/items/7c54461af68d3d29d7f2)
の続きです。
ぎりぎりの英語力でなんとか翻訳できました。
ビルドしてみます。
<img width="572" alt="スクリーンショット 2016-07-22 19.13.05.png" src="https://qiita-image-store.s3.amazonaws.com/0/74133/62233d73-72fc-055d-1b45-4c3f7e2a2fe3.png">
生成されたHTMLを見て出来栄えを確認してみます。
HTMLは下記ディレクトリに作られます。
<img width="1250" alt="スクリーンショット 2016-07-22 19.18.37.png" src="https://qiita-image-store.s3.amazonaws.com/0/74133/689420ab-2237-64e3-58d5-1a03131c0184.png">
問題なければ自分のリポジトリにプッシュします。
※upstreamから、最近の変更を取り込んでプッシュしましょう。
## 5.ビルドしてCIをチェック(Travis CI)
cakephp/doc は Travis CIを採用しています。
[Travis CI](https://travis-ci.org/) で自分のGitHubアカウントを連携します。
プルリクエストを送る前に、自分のリポジトリでの実行結果を確認しておきます。
TravisCIにてプッシュしたリポジトリを確認してみると、
ビルドされてます。気長に待ちましょう。
<img width="1672" alt="スクリーンショット 2016-07-24 17.26.47.png" src="https://qiita-image-store.s3.amazonaws.com/0/74133/65a984f1-0df4-88c2-ae5b-25d020d8d494.png">
チェックがグリーンになったことを確認します。
GitHub上にもバッチがつきました。
## 6. ビルド結果が問題なければプルリクエストを作成・送信
GitHubでプルリクエストを作成します。
簡潔で構いません。書けたら送ってみましょう。
本家の3.0ブランチ(masterではない)に出すことを間違えないでください。
早ければ1日で、マージ・リジェクトの反応があると思います。
※プルリクエストに関してはこちらをご参考ください
[Qiita - 何も知らない人がGitとGitHubを独学で知る](http://qiita.com/iKenji/items/367e8344490dd37e14f0)
## 7. マージされる
お疲れ様でした！
<img width="1016" alt="スクリーンショット 2016-07-31 19.11.48.png" src="https://qiita-image-store.s3.amazonaws.com/0/74133/6a59b48d-e3f2-c58d-4405-c7cedfe133d9.png">
<hr>
<img width="1144" alt="スクリーンショット 2016-07-31 19.17.06.png" src="https://qiita-image-store.s3.amazonaws.com/0/74133/33294b26-ca38-5f2e-bf17-12f676d442f5.png">