GithubでPR(プルリク)を使って開発しよう

概要

PRとは

• プル・リクエスト、通称プルリクの略。
• 自分の開発したものを、チームで共有するための手順・ルール・マナーのこと。
• 意訳すると「これ使ってねー」的な申し出。

誰に向けての記事？

• これからGithubを使ってチーム開発しようという、日本のGithub初心者さん向けの導入です。
• 現在Githubで開発してるけど、実は雰囲気で使っている、というチームさんにも役立つはず。多分。
• Githubにpushができる、という知識は前提となります。
  • (あとでフォローしたいなあ）
• 普段は個人で開発してるけど、ハッカソンやゲームジャムでチーム開発に挑戦したいという方などにも、読んでもらえたら嬉しいです。
  • そこでPRなどの手順を踏むかどうかは別だけど、知らないより知っててもらえると助かります。

内容は？

• そもそも「リポジトリをどう使い分けるのか」という部分をおさらい
• ローカルリポジトリで開発した内容を、どうやいう形でPRにしたらいいのか。
  • PRする時の心得的なものもちょっと残しておきます。

免罪符

• こちらで書いている方法は「正しい方法」ではなく「とりあえずやってみよう」というものです。
• また、OSSに本格的に参加する人向けでもありません。
  • 英語での各種説明があるのでそちらを探しましょう。（OSSのPRは基本的に英語なので、英語が苦手な人はチャンスと思って勉強しましょう)

リポジトリの使い分けをしよう

なんでリポジトリの説明？

• 「PRの説明なのになんで？」って思うかもしれませんが、リポジトリの区別がつかないとあとで混乱します。
  • というか説明しにくいので、覚えてください。
• あとGitを使う時、初心者の人がまず混乱するのはリポジトリ周り（特に知らないと検索もしにくい）だと思うからです。
• まずはローカル、リモート、origin、upstreamなどの用語を整理して、リポジトリに対する概念的な理解を作ります。
• 用語としてそれぞれの関係が「なんとなく」つかめれば、実際の作業もわかりやすくなる。はず。

用語

• ローカルリポジトリ local repository

  • 自分の作業スペース(一般的には手元のPC)となる場所にあるリポジトリ。
  • 開発するときはこのローカルリポジトリで、開発のissue(解決すべき問題)ごとにbramchが分けられていることを前提とします。

• リモートリポジトリ remote repository

  • ローカルが作業スペース(手元)であるのに対して、遠隔(主にGithubとかのサーバー）にあるリポジトリのこと。

• upstream リポジトリ

  • リモートリポジトリの一種。upstreamは上流の意味。
  • 主導権がある開発者や組織のアカウントが抱えるリポジトリのことを意味します。
  • 自分だけで開発する場合は自分の作ったリポジトリがupstreamを兼任します。が、この導入はチームで開発するためのものなのであまり考慮しません。
  • できればチーム用のorganizationを作って、そこにリポジトリを置いてupstreamとしましょう。

• origin リポジトリ

  • リモートリポジトリの一種。自分が操作する権利があるもの。
  • Githubで作ったリポジトリなら、自分のアカウントが抱えているリポジトリがoriginです。
  • 自分のアカウントが開発したいソフトのリポジトリを抱えていない場合、上流(organizationや他の開発者のこと)から自分のアカウントにフォーク(qloneのこと)で持ってきましょう。
  • Githubの場合 https://github.com/　[AtsushiYamashita]　/Curriculm-Vitaeのように、抱えているアカウントの名前がリポジトリ名の前に付いています。これで判断しましょう。

• その他のリモート

  • リモートリポジトリの一種。
  • PRを承認する側になると、他の開発者のリモートリポジトリを手元にqloneしてくることがありますが、今回の説明ではこれを「その他」として扱います。
  • 逆にいうと、承認してもらうだけの立場ならあまり意識しません。

作業の前提

• originが自分のアカウントに設定されている

  • まずは自分のローカルリポジトリにremoteリポジトリが設定されているかを確認しましょう。
  • 確認方法1 : SourceTreeなどのGUIツールを利用している場合は、リポジトリの設定とかを開くと、リモートという項目で設定できるようになっています。
  • 確認方法2 : bashなどのCLIでgitを使っているならgit remote -vコマンドで自分がremoteに登録しているアドレスの一覧が見られます。
  • remoteリポジトリにはそれぞれアドレスに対応した名前が付いていると思いますが、その中にoriginという名前があり、自分のアカウントで抱えているリモートリポジトリが紐づけられていることを確認してください。
  • もし、originに自分の抱えているリモートリポジトリが設定されていなければ、設定し直してください。

• upstreamに上流のリポジトリが設定されている

  • この場合の「上流のリポジトリ」とは「公式なものとして扱うリポジトリ」のことです。
  • 自分のリモートリポジトリが、どこかからフォークしてきたものであれば、Githubだとforked fromという形でリポジトリ名の所に上流のリポジトリ名があるはずです。
  • 
  • もし、upstreamが正しく設定されていなければ、設定を直してください。

PRの手順

pushのルール

• branchの確認
  • ローカルで開発する時はmasterブランチではなく、開発用のブランチで作業していると思います。
  • していない人は今日から「ローカルのmasterはupstreamのmasterと同じ状態を維持する」という原則を覚えてください。
  • pushする時も、自分の開発用ブランチをoriginにpushする形になります。
  • 蛇足ですが、ローカルのmasterをupstreamのmasterと同期させていれば、originのmasterも結果としてupstreamのmasterと同期するはずです。
• pushの前に更新確認
  • 上記の「前提」を確認していれば、originとupstreamのリポジトリが、ローカルリポジトリに設定されていると思います。
  • upstreamは、自分がoriginにpushする前にfetchして、公式の更新を確認するために使います。
  • 短時間の作業でも、originにpushする前に必ずfetchして確認しましょう。世界中の人が参加している開発だとまれによくconflictします。
• 自分が動かしていいのは、自分のリポジトリだけ
  • 自分がpushするのは絶対に自分のoriginリポジトリです。upstreamにpushするのはルール違反です。
  • このあたりを曖昧にすると、どのリポジトリが本当の最新かよくわからないみたいな話になるので間違えないように注意してください。特にupstreamのmasterに直接pushとか、だめ、絶対。

PRの方法とマナー

• ブランチを選んでPRを作る
  • PRは常に、自分のリモートから上流のリモートへ行います。
  • PRするためには、Githubなら下図の位置にある「Branch:---」のリストから、PRしたいbranchを選択して、横のnew pull requestボタンを押すことで作成できます。(黄色い枠線でCompare & pull requiestと出ていることもあります)
  • 
• 自分のリポジトリから、上流のリポジトリへ
  • PR画面ではbase forkとして「誰の、どのbranchへPRを届けたいのか」を指定できます。
  • また、自分の開発したbranchが正しく選択されていることを確認してください。
  • 
  • (だいたい、自動でちゃんと選択されているはずです)
• PRを確認しやすいようにしよう
  • あとはcreate pull requestのボタンを押せば、PRそのものはできます。
  • ただし、PR（これ使ってね）をするからには「どんな問題をどう解決するのか」という説明は最低限書いておくのが望ましいです。
  • そこで、PRに以下のような内容を添えて、マークダウンでちょこっと読みやすくしてからPRしましょう。
  • また、右側のReviewerに「誰にチェックして欲しいか」とかを設定しておくと、より良いと思います。
  • 
  • もし自分がPRしたいリポジトリで標準的な表記方法が既にあれば、それを踏まえたもの、記述内容を合わせたものにしてください。

PRの確認(18/01/07追記)

• どこからのPRか？
  • 正しく上記の手順ができているか、自信がなければ確認する方法があります。
  • 
  • 図の上側のようにorigin:masterと管理しているアカウント : PRを届けたいブランチのような表記になっていれば大丈夫です。
  • 図の下側のように、PRが同じアカウントから出ていると、PRに関するアカウントの表示は省略されます。
• 具体例
  • MSのアカウントを見てみましょう。
  • ローカルから公式に対してPRをしているため、masterに管理側のアカウント名と、PRを送るブランチの名前が表示されています。
  • この開発ではmasterではなく、さらに一歩距離を置いて公式開発ブランチに対してPRを出しています。このようにする事で、安定版と不安定な開発を両立させています。
  • 

参考サイト

これでもうPRができないということはないでしょう！
とはいえ、そのまま投げっぱなしジャーマンでは無責任すぎるので、参考サイトなどをいくつか。

PR手順やルールの参考になるサイト

• Qiita "GitHubのIssueやPull requestで頻出する英語の略語達" - @iguchi1124 : https://qiita.com/iguchi1124/items/a9688010b82b821071b8
• Thinkful "GitHub Pull Request Tutorial" : https://www.thinkful.com/learn/github-pull-request-tutorial/
• Stackoverflow "Best practice for Pull Requests on GitHub ": https://stackoverflow.com/questions/28880011/best-practice-for-pull-requests-on-github
• Github "How to write the perfect pull request" : https://github.com/blog/1943-how-to-write-the-perfect-pull-request

PRするときの内容について

• Good practice
  • https://github.com/Microsoft/MixedRealityToolkit-Unity
  • 簡潔でわかりやすいルール、日本的な組織の導入向き。
• Bad practice
  • https://github.com/facebook/draft-js
  • 細かいことを気にしないで、思い思いのPRをするとどうなるか。

まとめ

上記の内容を一通り確認してもらえれば、とりあえず「PRしてねー」と言われた時に「何をしたら良いのかわからない」的な状態は回避できるはずです。
あと、最初にも書いてありますが、これは日本人が日本の組織で、とりあえずPR使ってみようかみたいな時の導入です。「PR日本語かよ」とかのツッコミはなしで。

ここまで読んでもらってありがとうございます。
「こういうサイトもある」「この手順も導入時に覚えてくれよ」「そもそも内容として間違っている」などありましたら、お気軽にコメントください。