「EbookFoundation/free-programming-books」にコントリビュートしよう！ガイドラインや手順など解説するよ
EbookFoundation/free-programming-booksとは
無料で公開されているプログラミングに関するWebサイトや電子書籍へのリンク集リポジトリです。
スター数が13万近くあり現時点で7位に位置していたり、コントリビューターが1000人超えていたりとかなり大きめのリポジトリです。
英語だけと思いきや日本語版もあります。
日本語版には現時点ではてブ数105付いています。
課題
日本語版をぱっと一通り見てもらえれば分かると思うのですが、情報が古い、リンク切れ多い、あの言語無いの？あのサイトは載ってないの？など思いませんでした？
私は思いました😞
- JavaScriptにAngularやReactあってもVueが無い
- PythonにFlaskあってもDjangoが無い
- TypeScriptにはリンクが1個しかなくしかもリンク切れ
などなど
なぜなら、コントリビューター1000人超えているといっても、日本語版のコントリビューターは現時点で35人しかいません。
さらにここ数年は年数回しかコミットされていないなどあまり活発的に更新されている印象はありませんでした。
プルリク投げた
気になった + 直すことができる = プルリク！
まずリンク切れが多かったのが気になり、何個か調べたらURLが変更された程度のものがあったのでそれを修正しました。
Update free-programming-books-ja.md #3373
https://github.com/EbookFoundation/free-programming-books/pull/3373
Issuesに日本語リンク切れ修正の要求が上がっていたので上記を対応したついでに修正しました。
Fix #3271 Broken Japanese links #3375
https://github.com/EbookFoundation/free-programming-books/pull/3375
はてブで見かけたのでC++入門を追加しました。
Add C++ introduction to free-programming-books-ja.md #3376
https://github.com/EbookFoundation/free-programming-books/pull/3376
リンク1個の変更でもプルリク投げて大丈夫です！
英語なんて単語組み合わせばOK！
あなたもプルリク投げてみましょう！！！！
コントリビュートする方法
0. CONTRIBUTING.md を読む
貢献の仕方が書かれています。具体的にはリンクの順番やフォーマットなどのガイドラインは目を通しておきましょう。
下記が特に重要そうな所をざっくり日本語に訳したものになります。
- 無料の本であること（海賊版やその人だけに発行されたURLではないこと）
- Google DriveやDropboxなどファイルアップロードプラットフォーム上に無いこと
- リンクはアルファベット順に並んでいること
- 信頼できるソースであること
- httpsを優先すること（httpでもリダイレクトあるからセーフなんてことはない）
- URLは短くすること
- ルートドメインで公開されている場合は末尾スラッシュは記述しないこと (https://example.com)
- index.htmlなど省略可能なものは省略すること
- ただし短縮URLは使わないこと
- コミットは小さくすること（1つの追加/変更/削除で1コミットを推奨）
- 必要に応じて著者名を記述すること
上記はほんの一部ですので、原文をGoogle翻訳使って眺めましょう。
1. forkする
右上のForkをクリックして自身のリポジトリに持ってきましょう。
2. cloneする
コマンドで解説していきますが、SourceTreeでもGitKrakenでもVSCodeでもなんでもいいです。
git clone {forkしたリポジトリのURL}このコマンドを打つことでリポジトリを自身のローカルに持ってくることができます。
3. branch作る
ブランチ名ですが、issue解決が目的ならば #3456 のように #{issue番号} とします。
それ以外はこれから何をやるのかを端的に示した名前をつけましょう。
git branch fix-ja-links4. 修正する
リンク集自体はMarkdownで記述されています。フォーマット知らなくてもリストやリンクの書き方など分かるかと思います。
VSCodeのMarkdown拡張機能によっては保存時にリスト表記を*から-に自動変更してしまう場合があるので設定で無効化しましょう。
5. lintかける
この辺の手順はガイドラインに載ってませんし、プルリク投げると自動的にlintがかかるようになっています。ただ後から修正するよりは今のうちに修正してpushしたほうがスムーズに事が進みます。
npmで配布されているため、Node.jsのLTS版をインストールしましょう。
https://nodejs.org/ja/
そしてインストールと実行をします。
npm install -g free-programming-books-lint
fpb-lint .インストールは一度してしまえば後はこのコマンドを打つ必要はありません。
lintを実行して何も出力されなければOKです。何か出た場合は行番号と理由が記載されているのでそこを修正しましょう。
6. コミットする
lintで何も出なければコミットしましょう。
git addでコミット対象にし、git commitでコミットします。
git commit -m でコミットメッセージを記述します。コミットメッセージはこの変更が何を意味するのかを端的に示しましょう。
大体このような形になります。
追加の場合は、Add xxxxxx
変更の場合は、Update xxxxxx 、修正の場合は、Fix xxxxxxx
削除の場合は、Remove xxxxxx
git add free-programming-books-ja.md
git commit -m 'Fix broken link'上記は壊れていたリンクを修正したというメッセージになります。
後は4，5，6を繰り返して改善していきます。ただしコミットは小さくとしかガイドラインに記載されていませんが、変更点が多すぎるとレビューする側も大変なためプルリクもある程度まとまった小さなコミットの集合体にしていきましょう。具体的には1つのプログラミング言語ずつのプルリクにするなどですね。
7. pushする
今までの作業はローカルに変更を加えただけになるため、それらの変更をGitHubに反映する必要があります。
git push8. プルリク投げる
pushしても自身がforkしたリポジトリのブランチとなるため、このブランチをfork元のリポジトリに取り入れられるようにする作業です。
fork元のリポジトリを開くと緑色のCompare & pull requestボタンが表示されているのでそれをクリックします。
プルリク作成画面になります。テンプレートが用意されているので後はそれを埋めていくだけです。
Google翻訳使ってそれっぽい英語で十分です。
私はタイトルにどこに対して何をしたかを明示するため編集したファイル名入れたりしています。
またチェックリストも用意されているので、チェックしていきましょう。
✅重複していないか
✅著者が記載されているか
✅アルファベット順にソートされているか
✅必要な備考が記載されているか
⚠ プルリク先やブランチを間違えないこと
Create pull requestボタンを押せばプルリクが作成されます！🎉
時差の関係上0時以降にレビューされる事が多いです。
無事マージされました！やったね！
まとめ
あなたが貢献することで、これからプログラミングを学ぼうとする人の役に立ちます。
リンク1個追加でも貢献できます！改善できそうな事を見つけたら是非直してみましょう！
👍
※追記（2019/10/03）
EbookFoundation/free-programming-booksについてLT登壇しました。
😉