Microsoftは、様々な技術情報をMicrosoft Docsというサイトでまとめています。
ドキュメントの紹介範囲は広く、Microsoft製の技術のみとは限りません。また、このドキュメントはGithubで管理されており、だれでも修正依頼 (プルリクエスト）を出すことができます。
今回は、PWAのサイトで一部古いEdgeブラウザを前提とした記述とスクリーンショットがあったので、新しい記述とスクリーンショットをプルリクエストで提案してみました。
プルリクエスト対応が数ヶ月ぶりでやり方を半分忘れていたことと、Contribution License Agreement (CLA) の確認が出るところが初めてだったので、今後プルリクエストを出すときに忘れないようにということで整理してみました。
1. Microsoft Docsについて
Microsoft Docsとは、様々な技術情報がまとまったサイトです。冒頭のスクリーンショットの通り、Azure、Visual Studio、Xamarinなど色々あります。
また、直接リンクがありませんが、Progressive Web Apps (PWA)など、Microsoft起源の技術ではないものも紹介されています。
もちろん、Windows Mixed Realityに関するドキュメントもあります。
このドキュメントのページには、Edit (編集) ボタンがあり、ここを押すとGithubの画面に遷移します。あとは、ここからプルリクエストを送ります。
2. プルリクエストを送る手順
プルリクエストとは、誰かの作っているリポジトリに対して、自分の修正範囲を反映してほしいとお願いすることです。
Githubにおいて、プルリクエストを行う方法は大きく３つあります。
(1) 誰かのリポジトリを自分のGithubアカウントにコピー(フォーク)して、その中で修正してからプルリクエストを出す
フォークの手順です。
ここではa-frameというリポジトリをフォークしています。フォーク後は自分のリポジトリとして扱えるので、クローンしてVisual Studio Codeなどで自由に編集できます。
コミット、プッシュ、ブランチ作成などをしても、a-frameリポジトリには影響しません。
フォークをしたら、Visual Studio Codeなどのエディタを使って修正し、プッシュまで行います。
pushまで実行した後で、New pull requestを選択します。
自分のブランチが、どこにマージされるかを選択して、説明文を書いてからCreate Pull Requestボタンを押すと完了です。
(2) Github上の修正したいリポジトリでペンマークを選択して、直接編集してからプルリクエストを出す
下記の画像のようにペンマークを選択すると、直接編集できるようになります。
このとき、以下の警告文が出ます。
You’re editing a file in a project you don’t have write access to. Submitting a change to this file will write it to a new branch in your fork "Githubアカウント名" /"今回の対象となるリポジトリ名称", so you can send a pull request.
ここには、以下のようなことが書いてあります。
・このリポジトリを直接編集する権限がない. ・ここで修正は可能。修正したら、自分のGithubリポジトリにフォークされた上でプルリクエストが選択できるようになる
(1) で書いたフォーク、自分のリポジトリで修正、プルリクエストを出すという手順は変わりませんが、フォークと自分の環境でクローンするという手間が省けます。
詳しい手順はこちらがわかりやすかったので、ご参考ください。
(3) 本体のリポジトリでブランチを作って、そこでプルリクエストをたてる
フォークしなくて良いのでシンプルでよいですが、OSSとしてプルリクエストを受け付けているリポジトリをいくつか調べたところ、直接作ったブランチからはプルリクエストをあげることはできないようでした。
こちらの記事を見ると、フォークしてからプルリクエストをあげると書いてあるので、(1)か(2)の方法で実施すると考えた方がよさそうです。
pull request の送信 - Contributor Guide | Microsoft Docs
ただし、いずれの方法であっても、始める前にCLAに同意することが前提です。
3. Contribution License Agreement (CLA)とは？
CLAとは、Contribution License Agreementの略で、OSS活動するにあたり守るべき条項です。先ほどの(1)か(2)の方法でMS Docsのプルリクエストを発行すると、初回の場合、以下のようなライセンスのページが表示されます。
Sign in with Github to agree ボタンを押すと、このような画面が出ます。
これは、MicrosoftがGithubアカウントを持つユーザのemailアドレスを読み取りますということを承認してください、という内容です。
これを承認すると、github上の名前やメールアドレスの確認欄が出て、入力を終えるとCLA対応は完了です。
4. おわりに
慣れると簡単ですが、しばらく経つと忘れてしまうので、たぶんまた見返すと思います。何か新しいことがあれば追記していく予定です。
