From 2f9a4d804aefc7733f3f304db406ea9c3b1c52f8 Mon Sep 17 00:00:00 2001 From: syuilo Date: Mon, 23 Aug 2021 23:37:52 +0900 Subject: [PATCH] Create CONTRIBUTING.md --- CONTRIBUTING.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..bfd07ea --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,61 @@ +# Contribution guide +プロジェクトに興味を持っていただきありがとうございます！ +このドキュメントでは、プロジェクトに貢献する際に必要な情報をまとめています。 + +## 実装をする前に +機能追加やバグ修正をしたいときは、まずIssueなどで設計、方針をレビューしてもらいましょう(無い場合は作ってください)。このステップがないと、せっかく実装してもPRがマージされない可能性が高くなります。 + +また、実装に取り掛かるときは当該Issueに自分をアサインしてください(自分でできない場合は他メンバーに自分をアサインしてもらうようお願いしてください)。 +自分が実装するという意思表示をすることで、作業がバッティングするのを防ぎます。 + +## Tools +### Jest +このプロジェクトではテストフレームワークとして[Jest](https://jestjs.io/)を導入しています。 +テストは[`/test`ディレクトリ](./test)に置かれます。 + +テストはCIにより各コミット/各PRに対して自動で実施されます。 +ローカル環境でテストを実施するには、`npm run test`を実行してください。 + +### tsd +このプロジェクトでは型のテストを行うために[tsd](https://github.com/SamVerschueren/tsd)を導入しています。 +Jestによるテストでは「型が期待したものか」というのはチェックすることができません。tsdを使うことで、型が意図したものであることを担保することができます。 +tsdによる型テストは[`/test-d`ディレクトリ](./test-d)に置かれます。 + +テストはCIにより各コミット/各PRに対して自動で実施されます。 +ローカル環境でテストを実施するには、`npm run test`を実行してください。 + +### API Extractor +このプロジェクトでは[API Extractor](https://api-extractor.com/)を導入しています。API ExtractorはAPIレポートを生成する役割を持ちます。 +APIレポートはいわばAPIのスナップショットで、このライブラリが外部に公開(export)している各種関数や型の定義が含まれています。`npm run api`コマンドを実行すると、その時点でのレポートが[`/etc`ディレクトリ](./etc)に生成されるようになっています。 + +exportしているAPIに変更があると、当然生成されるレポートの内容も変わるので、例えばdevelopブランチで生成されたレポートとPRのブランチで生成されたレポートを比較することで、意図しない破壊的変更の検出や、破壊的変更の影響確認に用いることができます。 +また、各コミットや各PRで実行されるCI内部では、都度APIレポートを生成して既存のレポートと差分が無いかチェックしています。もし差分があるとエラーになります。 + +PRを作る際は、`npm run api`コマンドを実行してAPIレポートを生成し、差分がある場合はコミットしてください。 +レポートをコミットすることでその破壊的変更が意図したものであると示すことができるほか、上述したようにレポート間の差分が出ることで影響範囲をレビューしやすくなります。 + +### Codecov +このプロジェクトではカバレッジの計測に[Codecov](https://about.codecov.io/)を導入しています。カバレッジは、コードがどれくらいテストでカバーされているかを表すものです。 + +カバレッジ計測はCIで自動的に行われ、特に操作は必要ありません。カバレッジは[ここ](https://codecov.io/gh/misskey-dev/mfm.js)から見ることができます。 + +また、各PRに対してもそのブランチのカバレッジが自動的に計算され、マージ先のカバレッジとの差分を含んだレポートがCodecovのbotによりコメントされます。これにより、そのPRをマージすることでどれくらいカバレッジが増加するのか/減少するのかを確認することができます。 + +## レビュイーの心得 +PRを作成するときのテンプレートに色々書いてあるので読んでみてください。(このドキュメントに移してもいいかも？) +また、後述の「レビュー観点」も意識してみてください。 + +## レビュワーの心得 +- 直して欲しい点だけでなく、良い点も積極的にコメントしましょう。 + - 貢献するモチベーションアップに繋がります。 + +### レビュー観点 +- セキュリティ + - このPRをマージすることで、脆弱性を生まないか？ +- パフォーマンス + - このPRをマージすることで、予期せずパフォーマンスが悪化しないか？ + - もっと効率的な方法は無いか？ +- テスト + - 期待する振る舞いがテストで担保されているか？ + - 抜けやモレは無いか？ + - 異常系のチェックは出来ているか？