BASE開発チームブログ

Eコマースプラットフォーム「BASE」( https://thebase.in )の開発チームによるブログです。開発メンバー積極募集中! https://www.wantedly.com/companies/base/projects

CakePHP Cookbook を直す方法(表示確認してからプルリクエストを出すまで)

はじめまして、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鍵の設定が必要です。以下の記事が参考になります。

monsat.hatenablog.com

準備が終わったら、Cookbook用のリポジトリにアクセスします。

github.com

ページ右上にあるForkボタンを押しましょう。

f:id:tenkoma:20180204033301p:plain

そうすると、自分専用のリポジトリが作成されます。

github.com

次にリポジトリをローカル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 をブラウザで開くと生成されたドキュメントを確認できます。

f:id:tenkoma:20180204044217p:plain

次にドキュメントのソースを修正します。今回は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での例です。

f:id:tenkoma:20180204050908p:plain

直したらビルドします。

$ 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

f:id:tenkoma:20180204054530p:plain

github.com

あとはマージしてもらえるのを待ちましょう。

補足

日本語以外の版もビルドしたい場合は以下のコマンドを実行します。

# 英語
$ 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にコントリビュートしたいエンジニアを募集しています!

*1:typo程度ならローカル作業不要ですが、修正箇所を見つけてないので…

*2:3系の最新版のドキュメントでも 3.0 ブランチを更新していきます

*3:2コミット以上のプルリクエストだと、プルリクエストのデフォルトタイトルがブランチ名になってしまうので、「[ja]Fix typo」などに変更しておきます