7.1 KiB
Contribution guide
プロジェクトに興味を持っていただきありがとうございます！ このドキュメントでは、プロジェクトに貢献する際に必要な情報をまとめています。
実装をする前に
機能追加やバグ修正をしたいときは、まずIssueなどで設計、方針をレビューしてもらいましょう(無い場合は作ってください)。このステップがないと、せっかく実装してもPRがマージされない可能性が高くなります。
また、実装に取り掛かるときは当該Issueに自分をアサインしてください(自分でできない場合は他メンバーに自分をアサインしてもらうようお願いしてください)。 自分が実装するという意思表示をすることで、作業がバッティングするのを防ぎます。
Issues
Issueを作成する前に、以下をご確認ください:
- 重複を防ぐため、既に同様の内容のIssueが作成されていないか検索してから新しいIssueを作ってください。
- Issueを質問に使わないでください。
- Issueは、要望、提案、問題の報告にのみ使用してください。
- 質問は、GitHub DiscussionsやDiscordでお願いします。
PRの作成
PRを作成する前に、以下をご確認ください:
- 可能であればタイトルに、以下で示すようなPRの種類が分かるキーワードをプリフィクスしてください。
- fix / refactor / feat / enhance / perf / chore 等
- また、PRの粒度が適切であることを確認してください。ひとつのPRに複数の種類の変更や関心を含めることは避けてください。
- このPRによって解決されるIssueがある場合は、そのIssueへの参照を本文内に含めてください。
CHANGELOG.mdに変更点を追記してください。リファクタリングなど、利用者に影響を与えない変更についてはこの限りではありません。- この変更により新たに作成、もしくは更新すべきドキュメントがないか確認してください。
- 機能追加やバグ修正をした場合は、可能であればテストケースを追加してください。
- テスト、Lintが通っていることを予め確認してください。
npm run test、npm run lintでぞれぞれ実施可能です
npm run apiを実行してAPIレポートを更新し、差分がある場合はコミットしてください。- APIレポートの詳細についてはこちら
ご協力ありがとうございます🤗
Tools
eslint
このプロジェクトではコードのフォーマットチェック/整形にeslintを導入しています。 CI上でも自動でチェックされ、ルールに則っていないコードがあるとエラーになります。
Jest
このプロジェクトではテストフレームワークとしてJestを導入しています。
テストは/testディレクトリに置かれます。
テストはCIにより各コミット/各PRに対して自動で実施されます。
ローカル環境でテストを実施するには、npm run testを実行してください。
tsd
このプロジェクトでは型のテストを行うためにtsdを導入しています。
Jestによるテストでは「型が期待したものか」というのはチェックすることができません。tsdを使うことで、型が意図したものであることを担保することができます。
tsdによる型テストは/test-dディレクトリに置かれます。
テストはCIにより各コミット/各PRに対して自動で実施されます。
ローカル環境でテストを実施するには、npm run testを実行してください。
API Extractor
このプロジェクトではAPI Extractorを導入しています。API ExtractorはAPIレポートを生成する役割を持ちます。
APIレポートはいわばAPIのスナップショットで、このライブラリが外部に公開(export)している各種関数や型の定義が含まれています。npm run apiコマンドを実行すると、その時点でのレポートが/etcディレクトリに生成されるようになっています。
exportしているAPIに変更があると、当然生成されるレポートの内容も変わるので、例えばdevelopブランチで生成されたレポートとPRのブランチで生成されたレポートを比較することで、意図しない破壊的変更の検出や、破壊的変更の影響確認に用いることができます。 また、各コミットや各PRで実行されるCI内部では、都度APIレポートを生成して既存のレポートと差分が無いかチェックしています。もし差分があるとエラーになります。
PRを作る際は、npm run apiコマンドを実行してAPIレポートを生成し、差分がある場合はコミットしてください。
レポートをコミットすることでその破壊的変更が意図したものであると示すことができるほか、上述したようにレポート間の差分が出ることで影響範囲をレビューしやすくなります。
Codecov
このプロジェクトではカバレッジの計測にCodecovを導入しています。カバレッジは、コードがどれくらいテストでカバーされているかを表すものです。
カバレッジ計測はCIで自動的に行われ、特に操作は必要ありません。カバレッジはここから見ることができます。
また、各PRに対してもそのブランチのカバレッジが自動的に計算され、マージ先のカバレッジとの差分を含んだレポートがCodecovのbotによりコメントされます。これにより、そのPRをマージすることでどれくらいカバレッジが増加するのか/減少するのかを確認することができます。
レビュイーの心得
PRのセクションをご一読ください。 また、後述の「レビュー観点」も意識してみてください。
レビュワーの心得
- 直して欲しい点だけでなく、良い点も積極的にコメントしましょう。
- 貢献するモチベーションアップに繋がります。
レビュー観点
- セキュリティ
- このPRをマージすることで、脆弱性を生まないか？
- パフォーマンス
- このPRをマージすることで、予期せずパフォーマンスが悪化しないか？
- もっと効率的な方法は無いか？
- テスト
- 期待する振る舞いがテストで担保されているか？
- 抜けやモレは無いか？
- 異常系のチェックは出来ているか？