背景

自分は普段 deno_lint の開発を行っています。Deno に組み込みのリンターで、TypeScript / JavaScript のコードを静的に解析して問題のあるコードを発見してくれるツールです。

JavaScript界のデファクトスタンダードなリンターである ESLint およびその TypeScript 拡張版の typescript-eslint が提供している "recommended" なルールとの互換を目指しています。
つまり、ESLint / typescript-eslint が推奨ルールとして提供しているルールを、deno_lint でも再実装して提供を行いたいということです。

一応、ある時点での "recommended" ルールは移植が完了しているのですが、その後 "recommended" ルールが追加されていないのか？ということをウォッチできていませんでした。もし追加されていたら、追従する必要があります。

というわけで 2021/4/10 現在の typescript-eslint の "recommended" ルール一覧を見に行きます。

自分の環境では、以下のような感じで表示されました。

supported rules of typescript-eslint

magurotuna 2021/04/10

問題

これを見て僕は思いました。

「✔️ があまりにも見づらくないか？」と。

特に、@typescript-eslint/ban-ts-comment の行の ✔️ は背景色とかなり同化してしまっていて、極めて見づらいと感じます。
自分が使っているGitHubカラーテーマは、最近追加された Dark dimmed です。カラーテーマを従来のライトモード（白背景）に戻してみると、✔️ はまったく問題なく視認することができました。

対応策

これに対する対応策として、✔️ ではなく ✅ を使う、というのを考えました。
こちらのタイプのチェックマークであれば、黒背景でも白背景でも視認しやすそうです。（参考: https://emojipedia.org/check-mark-button/ )

magurotuna 2021/04/10

着手

サクっと修正してPRを送ってみようと思います。

一応、typescript-eslintのコントリビュートガイドがあるので、これをチラ見しました。
ここには「issueあげてからPull Requestしてね」といったことが書かれていそうな気配がしますが、しかし今回やりたいようなドキュメントの軽微な修正だけの場合は issue をスキップしても良いと判断して、いきなりコードの修正から入ってしまおうと思います。
（実際、タイポを直すだけの修正の場合には、いきなりPRを出しているということが過去の状況から明らかです。例: https://github.com/typescript-eslint/typescript-eslint/pull/3243 )

実作業に入っていきます。リポジトリを fork して、clone して、ブランチを切ります。

該当のファイル packages/eslint-plugin/README.md 中に現れる ✔️ を ✅ に置換します。
ファイル中では ✔️ は :heavy_check_mark: と表現されていました。これを ✅ を表す :white_check_mark: に一斉置換します。
（参考: GitHub の markdown で使える emoji リスト https://gist.github.com/rxaviers/7360908 ）

作業はこれだけかなと思いましたが、念の為 :heavy_check_mark でリポジトリ内を全検索してみたら、markdown ファイル以外のところで :heavy_check_mark: が存在していることが判明しました。（こことか）

コードを眺めると、ルール一覧はコードによって自動生成されていて、さらに "recommended" なルールに対してちゃんと ✔️ が表示されていることをテストしているようでした。よくできてる。
なので一覧生成のコードおよびテストコードにも手を入れる必要がありそうです。直しました。

最後に、コントリビュートガイドに記載されている以下のコマンド群を実行して、テストなどを問題なくパスすることを確認します。

yarn format
yarn typecheck
yarn test
yarn lint
yarn lint:markdown
yarn check:spelling
yarn check:configs
yarn check:docs

無事にパスしたので、PRを立てていきます！

magurotuna 2021/04/10

PR を立てる

PR を立てます。先のコントリビュートガイドをもう一度読むと、PRのタイトルのフォーマットが決まっているようです。

<tag>(<package>): <short description>

このフォーマットに従い、今回立てるPRのタイトルを

docs(eslint-plugin): switch check marks to :white_check_mark: for visibility

と決めました。「見やすさのためにチェックマークを :white_check_mark: に変更しました」って感じです。

タイトルが決まったので、次は本文を考えます。PRのテンプレートが決まっているプロジェクトもありますが、typescript-eslint は特にテンプレートはないようなので、すべて自分で考えます。

本文の書き方はいろいろ流儀があると思いますが、僕の場合は

まず、何をしようとしているPRなのかを端的に説明する
次に、なぜこの修正が必要だと思ったのか、このPRが取り込まれるとどんな良いことがあるのか、懸念事項はあるか、などを書く

といった感じでやっています。

まず「端的に説明する」ですが、今回は「:heavy_check_mark: を :white_check_mark: に変更しました」という内容を伝えたいので

This patch switches :heavy_check_mark: to :white_check_mark: in the supported rules table.

と書きました。ほぼPRタイトルと同じ内容ですが、まあ大丈夫だと思います。

次にその他の細々した内容を書いていきます。「なぜ変更しようと思ったのか？」「変更されたらどんな感じで見やすくなるのか？」を説明することが必要と考え、

変更しようと思った動機は、ダークテーマだと :heavy_check_mark が極めて視認しにくく、:white_check_mark: であればテーマを問わず見やすいようになるから
変更されたら各カラーテーマでの見た目はこうなりますよ、というスクショ

を書くことにして、結果的に以下のようなPRを立てました。

magurotuna 2021/04/10

おわり

「OSSに貢献したいけど何からやればいいのかわからない」といった質問をもらうことがあるので、僕の場合こうやってますよというのを書いてみました。
すでに起票されている issue からとっていくのが王道ではありますが、今回のようにドキュメント修正などは自分が気づいたらパッと修正してPRを送ってしまう、という感じで気軽にやっていけると思います。

取り組む課題を見つける（good-first-issue が付いている issue を見つける、ユーザーとして使ってみてバグを見つける、ドキュメントのミスを見つける、など）
プロジェクトごとのお作法に従う（今回のケースであればコントリビュートガイドをしっかり読む）
コードベースが巨大すぎて、どこを修正すべきなのか見当もつかない場合は、コードのアーキテクチャガイドやコントリビュートしたい人向けのコード解説の資料がないか探してみる（ARCHITECTURE.md という名前で用意されていることが多い。例えば ESLint のこれなど）
PR の本文で必要十分な情報を書くようにがんばる

これらを心がけつつ、いくつかコントリビュートしてみると、だんたん慣れてくると思います！
Happy contributing 💻