ガチの開発者じゃなくても少しは貢献できる！それが「README.mdの翻訳」作業です。
少しの英語力と、気力と度胸があればとりあえず実施できる。勉強にもなるし、誰かの助けになるかもしれない。もっとちゃんとした日本語情報が広まるきっかけになるかもしれない。
というわけで、できるところから挑戦してみました。プルリクってやつを。
今回の対象リポジトリ
今回、私が翻訳に挑戦したのは、IBM Code Patterns サイトの Call for Code で紹介されている以下の GitHub リポジトリです。
日本語の紹介ページはこちら
じつはこの Code Patterns サイトの場合、いちばん大変で英語力が必要な「概要」部分は既に日本語に翻訳してくれているんですよ。内容を日本語で理解できますし、残りの手順などは訳し易いので、実は非常にお勧めのネタだったりします。みなさんも是非！
そしてこのパターンの場合、既に中国の方が中国語のREADMEをプルリク済みだったので、それを真似てプルリクしてみたわけです。なにせ初めてで怖かったので…
私の環境と事前準備
さて、私の環境と今回の利用ソフトウェアは以下です。
- Windows 10 64bit
- Chrome Webブラウザ (GitHubサイトアクセス用)
- GitHub Desktop
- ATOM テキストエディタ (MarkDown形式のテキスト編集用)
コマンドラインツールは一切使わず、Web サイトと GitHub Desktop の操作だけでプルリクを実行しています。初心者の方に特にお勧めの方法です。
GitHub Desktop は今回の主要アプリですので、ぜひ入れてみてください。コンソール版のほうが機能豊富なのですが、まあ、それ使える人はこのページ読んでいないと思うのでw
GitHub のアカウントを作成し、GitHub Desktopにセットしておいてください。いよいよ登場！初心者こそ知っておきたいGitHub Desktopの使い方 など参考になります。
プルリクの手順
1. 自分のリモート・リポジトリにフォークする
まずはChrome Webブラウザで GitHubサイト にアクセスし、ログインしておきます。
対象のリポジトリを開き、右上にある Fork ボタンをクリックします。
すると対象リポジトリが、自分のアカウントの下(リモート・リポジトリ)にコピーされます。
これは単なるコピーではなく、元のリポジトリとの連携を維持した「フォーク」になります。タイトルの下に小さな文字で「forked from xxxx」と表示されているのがわかりますね。
2018年10月19日 追記
この記事の手順で何回かプルリクを実施しましたが、問題なく実施できました。
ただし一般的にプルリクの手順としてブランチを切るのが一般的ですし、自分が何か失敗したときにやり直しが楽ですし、なによりブランチの名前で目的が明確にしておくことで皆に修正の意義を理解してもらえます。
というわけで、フォークした直後に以下のようにブランチを作成することをお勧めします。そして以降はこのブランチのほうを対象に、同様の手順で進めてください。
2. ローカル・リポジトリにクローンする
いよいよ GitHub Desktop アプリの出番です。「Clone a repository」を実行すると自分のリモート・リポジトリ(GitHubサイトで自分のアカウントの下にあるリポジトリ)の一覧が表示されますので、さきほどフォークしたリポジトリを選択します。
すると選択したリポジトリがローカルに「クローン」されます。ファイルを全部ローカルにダウンロードする、と言ったほうがわかりやすいかも。
3. ファイルを変更する
さて、クローンされたローカルファイルを相手に、いよいよ変更を加えていきます。
使い慣れたアプリケーションで良いと思いますが、私は ATOM エディタ を使用しています。標準で .md ファイルのプレビュー機能があり、快適に作業ができます。
今回の私の場合は、README.md ファイルを README-ja.md というファイル名でコピーして、中身を翻訳していきます。また元の README.md ファイルのほうも、先頭のほうに README-ja.md ファイルへのリンクを追加しておきます。
4. 変更をコミットする
修正が終わったら GitHub Desktop に戻ります。
Changes の欄に変更されたファイルが並び、その右に変更点(変更差分、Diff)が表示されています。関係ないところまで間違えて変更しちゃってないか、念のためよーく確認しましょう。
特に既存ファイルの修正の場合、変更点をよーく確認しておきます。一部のエディタで改行コードを自動的に変換する設定になっていると、それが全部変更点として認識される場合もあります。この場合は設定を見直し、よけいな変更がされないようにします。
さて、変更点に問題なければ、変更のタイトルと変更内容を入力して「Commit to master」ボタンを押します。これでローカル・リポジトリ(ローカルPC上のリポジトリ)に変更がコミット(反映、確定)されます。
5. 変更をプッシュする
さて、このままだと、まだローカルPC上のリポジトリを更新しただけです。GitHub Desktopの上にある「Push origin」ボタンを押して、GitHub Web上にある自分のリモート・リポジトリに反映(アップロード)します。
アップロード後、自身の GitHub Web アカウント上のリモート・リポジトリを開き、更新が反映されていることを確認しましょう。
.md ファイルの場合、表示の最終確認、特にページ内リンクの動作確認はこの段階でするのがお勧めです。また複数人で作業している場合や、成果物のレビューアーが居る場合には、この段階でのURLを知らせて内容を確認してもらいます。
6. プルリクを送る
GitHub Web 上で確認が終わったら、いよいよプルリクを送ります。
GitHub Web上の自分のリモート・リポジトリを開き、上にある「New pull request」ボタンを押します。
すると更に確認画面が表示されます。
矢印の左側がこれからリクエストする先、オリジナルのリポジトリです。矢印の右側が今回修正した、自身のリモート・リポジトリです。
問題がなければ再度「Create pull request」ボタンを押します。
やっと！これでプルリクの入力画面が表示されます。タイトルと概要には先ほどコミットしたのと同じテキストが自動で入力されているはずです。違っていたら適時修正してください。念のために下の変更点も最終確認しておきましょう。
そして下にある「Create pull request」ボタンを押してプルリク(変更をプルしてもらうリクエスト)は完了です！以下のような確認画面が出るので、ブックマークなどしておきましょう。
私の場合はラッキーなのことにすぐに承認いただけて、オリジナルのリポジトリに反映(マージ)してもらえました。
全体の流れ
今回のプルリクの流れを簡単に図にしましたので、参考にしてみてください。
最初のフォークと、最後のプルリクは GitHub Web で実行します。残りは GitHub Desktop での実行になります。
実は最初、全部を GitHub Desktop でやろうとしたんです。が、思ったより面倒で、しかもちょっと失敗してしまい… 結局、最初のフォークと最後のプルリクはGitHub Webで実施したほうが間違いにくいし、説明も楽だな、と思った次第です。
GitHub Desktop は実は多機能だったりしますが、使う際には自分のリモート・リポジトリとローカルPC上のローカル・リポジトリの二つに限定して操作したほうがわかりやすいし、便利だと思うのです。あくまで個人的な感想なのですが。
というわけで
無事に初のプルリクを実施できたので、自分の体験をざっとまとめてみました。
コマンドラインを使わず、GitHub Web と GitHub Desktop の操作だけで完結するので、ちょっとした修正をプルリクしたい、初心者の方に特にお勧めではないかとおもいます。
翻訳だけでも立派な貢献です、自分の勉強を兼ねて、積極的にチャレンジしてみましょう！
ではでは。