91 lines
7.1 KiB
Markdown
91 lines
7.1 KiB
Markdown
# Contribution guide
|
||
**[✨ English version available](/docs/CONTRIBUTING.en.md)**
|
||
|
||
プロジェクトに興味を持っていただきありがとうございます！
|
||
このドキュメントでは、プロジェクトに貢献する際に必要な情報をまとめています。
|
||
|
||
## 実装をする前に
|
||
機能追加やバグ修正をしたいときは、まずIssueなどで設計、方針をレビューしてもらいましょう(無い場合は作ってください)。このステップがないと、せっかく実装してもPRがマージされない可能性が高くなります。
|
||
|
||
また、実装に取り掛かるときは当該Issueに自分をアサインしてください(自分でできない場合は他メンバーに自分をアサインしてもらうようお願いしてください)。
|
||
自分が実装するという意思表示をすることで、作業がバッティングするのを防ぎます。
|
||
|
||
## Issues
|
||
Issueを作成する前に、以下をご確認ください:
|
||
- 重複を防ぐため、既に同様の内容のIssueが作成されていないか検索してから新しいIssueを作ってください。
|
||
- Issueを質問に使わないでください。
|
||
- Issueは、要望、提案、問題の報告にのみ使用してください。
|
||
- 質問は、[Misskey Forum](https://forum.misskey.io/)や[Discord](https://discord.gg/Wp8gVStHW3)でお願いします。
|
||
|
||
## PRの作成
|
||
PRを作成する前に、以下をご確認ください:
|
||
- 可能であればタイトルに、以下で示すようなPRの種類が分かるキーワードをプリフィクスしてください。
|
||
- fix / refactor / feat / enhance / perf / chore 等
|
||
- また、PRの粒度が適切であることを確認してください。ひとつのPRに複数の種類の変更や関心を含めることは避けてください。
|
||
- このPRによって解決されるIssueがある場合は、そのIssueへの参照を本文内に含めてください。
|
||
- [`CHANGELOG.md`](/CHANGELOG.md)に変更点を追記してください。リファクタリングなど、利用者に影響を与えない変更についてはこの限りではありません。
|
||
- この変更により新たに作成、もしくは更新すべきドキュメントがないか確認してください。
|
||
- 機能追加やバグ修正をした場合は、可能であればテストケースを追加してください。
|
||
- テスト、Lintが通っていることを予め確認してください。
|
||
- `npm run test`、`npm run lint`でぞれぞれ実施可能です
|
||
- `npm run api`を実行してAPIレポートを更新し、差分がある場合はコミットしてください。
|
||
- APIレポートの詳細については[こちら](#api-extractor)
|
||
|
||
ご協力ありがとうございます🤗
|
||
|
||
## Tools
|
||
### eslint
|
||
このプロジェクトではコードのフォーマットチェック/整形に[eslint](https://eslint.org/)を導入しています。
|
||
CI上でも自動でチェックされ、ルールに則っていないコードがあるとエラーになります。
|
||
|
||
### 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/misskey.js)から見ることができます。
|
||
|
||
また、各PRに対してもそのブランチのカバレッジが自動的に計算され、マージ先のカバレッジとの差分を含んだレポートがCodecovのbotによりコメントされます。これにより、そのPRをマージすることでどれくらいカバレッジが増加するのか/減少するのかを確認することができます。
|
||
|
||
## レビュイーの心得
|
||
[PRのセクション](#PRの作成)をご一読ください。
|
||
また、後述の「レビュー観点」も意識してみてください。
|
||
|
||
## レビュワーの心得
|
||
- 直して欲しい点だけでなく、良い点も積極的にコメントしましょう。
|
||
- 貢献するモチベーションアップに繋がります。
|
||
|
||
### レビュー観点
|
||
- セキュリティ
|
||
- このPRをマージすることで、脆弱性を生まないか？
|
||
- パフォーマンス
|
||
- このPRをマージすることで、予期せずパフォーマンスが悪化しないか？
|
||
- もっと効率的な方法は無いか？
|
||
- テスト
|
||
- 期待する振る舞いがテストで担保されているか？
|
||
- 抜けやモレは無いか？
|
||
- 異常系のチェックは出来ているか？
|