誰でも出来る有名OSSへのコントリビュート #PHP

OSS ？コントリビュート？興味無いんだけど？
という方はこちらをどうぞ！

参考：意外ととっつきやすい OSS 開発参加方法まとめ-shunsuke227ono

どうやってコントリビュートする?

ドキュメントやリファレンスを GitHub で管理している OSS(オープンソースソフトウェア)があります。

例えば、PHP の Web アプリケーションフレームワークである CakePHP の公式リファレンス(CookBook) は、こちら(GitHub) で各国の言語に翻訳されて管理されています。

英語で書かれている本家ドキュメントを日本語へ翻訳することでコントリビュートします。
エンジニアリング感はあまり無いですが、これをやることで下記メリットを得られるのではないかと思います。

英語の勉強になる
実際のプルリクエストのフローを体感できる
GitHub の理解度が高まる
頑張ればコミッターになれる(かも?)

(参考：Qiita - CakePHP3公式ドキュメントの翻訳が一石N鳥だった件

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

コントリビュートの方法が書いてあります。
今回の目的はリファレンスの翻訳ですので、
一番下の行の「ドキュメントへコントリビュートする」のリンク先をみます。

こちらが 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
~~~~~~~~~~~~~~~~~~~~~~~~~

適当に雰囲気を読み解くと...

これは CakePHPの公式ドキュメント

master ブランチは CakePHP 2.x のものだから、CakePHP3.x は3.0ブランチを見てください

コントリビュートする方法は2種類ある。ひとつは Docker を使ってドキュメントをビルドする方法です

3. 開発環境を構築(Docker or Vagrant)

翻訳作業をする環境を構築します。
CakePHP のドキュメントは Sphinx で構成されています。
Docker でコンテナを作ってビルドするのが推奨みたいですが、Sphinx をビルドさえ出来ればいいので、
今回は vagrant と virtualbox を使って sphinx が使える Ubuntu環境 を作ります。

vagrantとvirtual-boxに関してはこちらをご参考ください
※だいたいの雰囲気がわかったら "vagrant up"する前に戻ってきてください
sphinxの記法については知らなくても大丈夫です。

参考：Vagrant+VirtualBoxでUbuntu環境構築

参考：VagrantとDockerについて名前しか知らなかったので試した

上のリンクを参考に、"vagrant up" を実行出来る環境になったら
Sphinxビルド用の Vagrantfile(設定ファイル)をこちらに用意して頂きましたので
"git clone" もしくは右上のボタンから"Download ZIP"してください。
ディレクトリ名は何でも大丈夫です!!

ディレクトリの準備ができたら、Vagrantfile と provision.sh があるディレクトリで "vagrant up"　コマンドを実行します。これだけで PC内に仮想のubuntu環境ができあがります。
vagrantって便利！

次に、ビルドする CakePHP のドキュメントを準備します
その前に...Git/GitHubがよくわからない方はこちらをどうぞ

参考：新入社員による新入社員のためのGit

参考：GitHub 初心者による GitHub 入門（１）

本家 cakephp/docs リポジトリを fork して編集用のリポジトリを自分のGitHub上に作成します。

fork できたらローカルへ clone します。
"vagrant up"したディレクトリで
git clone git@github.com:iKenji/docs.gitコマンドを実行しましょう。
鍵とかよくわからない...という方は↓
git clone https://github.com/iKenji/docs.git
で GitHub のID/PASSで clone できます。
※URLは画像を参考に自分のリポジトリのものを指定してください。

これで、本家リポジトリを 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. 翻訳

まずは、翻訳するページを決めます。
公式リファレンス上で日本語が無いページを探します。
私は、業務上読みたいページで日本語が無い、かつボリュームが少なめページを選びました。

今回は、CakePHP3のCookieComponentのページを翻訳します。
http://book.cakephp.org/3.0/ja/controllers/components/cookie.html

GitHub上での表示は下記のようになっています。

翻訳作業をするその前に

ローカルのリポジトリを最新の状態にしておきましょう。

$ 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

日本語のみビルドします。