はじめまして、2017年9月に入社したBack-End Engineer の田中です。アプリケーションが使うPHP/CakePHPのバージョンアップを担当しています。
BASE ではサーバーサイドアプリケーションの大部分がCakePHP2を使って構築されています。 日常的にCookbookやCakePHPコアのコードを読んでいて、時々typoや不具合を見つけてはプルリクエストを送っています。 PHP 7.2 でテストスイートをパスさせる修正もしたので、PHP7.2 でも動くはずです。
CakePHPユーザーの方で、ドキュメントにtypoを見つけたことはありませんか？ドキュメントへの貢献についてのページを読むと、まずはメールを送る必要があるようなことが書いてあり面倒そうに思えますが、実際のところプロジェクトがGitHubに移行してからはいきなりプルリクエストを送っても問題ないようになっています。この記事ではドキュメントをPCで修正してプルリクエストを送る方法を説明します。
この記事の内容は2018/02/08にランサーズ株式会社で開催されたCakePHPクックブックを直してみよう勉強会 - connpassで解説した内容に多少の修正を加えたものです。
CakePHP のドキュメントを直す
CakePHP Cookbook 日本語ドキュメントはボランティアベースで翻訳されています。 翻訳率はかなり高いですが、typoや読み取りづらい部分が見つかることがあります。 CookbookはGitHubでホストされているので、GitHubアカウントさえあれば、修正してプルリクエストすることができます。以下の記事をご覧ください。
こちらの方法だと、PCにリポジトリをコピーしなくてもよいので、簡単に修正依頼できますが、表示確認ができません。 マークアップやサンプルコードを含めて修正するときは、表示確認したくなります。 その場合はローカルPCで作業する必要がありますのでその方法を説明します。
目次
- リポジトリをコピーして作業を始めるまで
- テキストを修正してローカルビルドする
- プルリクエストを作成する
- 補足
リポジトリをコピーして作業を始めるまで
事前の準備としてgitインストールとSSH鍵の設定が必要です。以下の記事が参考になります。
準備が終わったら、Cookbook用のリポジトリにアクセスします。
ページ右上にあるForkボタンを押しましょう。
そうすると、自分専用のリポジトリが作成されます。
次にリポジトリをローカルPCにクローンします。 [your-name] はあなたのGitHubアカウント名に置き換えてください。
$ mkdir -p ~/src/github.com/cakephp $ git clone git@github.com:[your-name]/docs.git ~/src/github.com/cakephp/docs
常に最新のソースファイルから作業に着手するために、オリジナルのリポジトリを upstream として登録しておきます。
$ git remote add upstream git@github.com:cakephp/docs.git
最後にDocker をインストールします。ドキュメントをビルドするために必要な環境を簡単に構築できるようになっていますので、手元のPCにインストールしてください。 Docker Storeから、お使いのPCのプラットフォーム向けインストーラをダウンロードして、インストールしてください。
https://store.docker.com/search?type=edition&offering=community
テキストを修正してローカルビルドする
まずは、手元でドキュメントをビルドして、ブラウザで確認してみましょう。以下のコマンドを実行します。
$ cd ~/src/github.com/cakephp/docs $ docker build -t cakephp/docs . $ docker run -it --rm -v $(pwd):/data cakephp/docs make html-ja
2行目の docker build ... でビルドに必要なツールをインストールして、3行目の docker run ... でビルドします。
生成されたWebページは build/html/ja ディレクトリ以下にあります。 build/html/ja/index.html をブラウザで開くと生成されたドキュメントを確認できます。
次にドキュメントのソースを修正します。今回はCakePHP3 Cookbook で見つけたtypoを修正してみましょう。 *1 upstream/3.0 *2 からブランチを作成します。
# オリジナルのリポジトリの状態をローカルに取得します $ git checkout 3.0 $ git fetch upstream $ git merge upstream/3.0 $ git checkout -b fix-ja-console Switched to a new branch 'fix-ja-console'
ソースを開いて修正します。ドキュメントソースのreStructuredText形式に対応しているエディタを使うのがよいでしょう。以下はPhpStormでの例です。
直したらビルドします。
$ docker run -it --rm -v $(pwd):/data cakephp/docs make html-ja
2回目以降は docker build 不要です。
表示が確認できたらコミットします。英語である必要がありますが、typoなら 「Fix typo」でOKです。
$ git commit -am '[ja]Fix typo'
プルリクエストを作成する
あとは、ブランチをプッシュして、プルリクエストをつくるだけです。
$ git push origin fix-ja-console
cakephp/docs: CakePHP CookBookを開くとプッシュしたブランチが表示されるので「Compare & pull request」を押し、「Create pull request」を押すとプルリクエストが作られます。 *3
あとはマージしてもらえるのを待ちましょう。
補足
日本語以外の版もビルドしたい場合は以下のコマンドを実行します。
# 英語 $ docker run -it --rm -v $(pwd):/data cakephp/docs make html-en # すべての言語 $ docker run -it --rm -v $(pwd):/data cakephp/docs make html
エンジニア募集
BASEではECプラットフォームを一緒に作ったりCakePHPにコントリビュートしたいエンジニアを募集しています！
