Sharkey/packages/misskey-js/CONTRIBUTING.md
Tom Anderson e333e7ced8
docs: Remove forum references and use Github Discussions (#12158)
* docs: Replace forum with Github Discussions

* Remove outdated forum link from CONTRIBUTING.md

* Remove outdated forum link from misskey-js/CONTRIBUTING.md

* Remove outdated forum link from misskey-js/docs/CONTRIBUTING.en.md

---------

Co-authored-by: かっこかり <67428053+kakkokari-gtyih@users.noreply.github.com>
2023-11-02 19:57:43 +09:00

7.1 KiB
Raw Permalink Blame History

Contribution guide

English version available

プロジェクトに興味を持っていただきありがとうございます! このドキュメントでは、プロジェクトに貢献する際に必要な情報をまとめています。

実装をする前に

機能追加やバグ修正をしたいときは、まずIssueなどで設計、方針をレビューしてもらいましょう(無い場合は作ってください)。このステップがないと、せっかく実装してもPRがマージされない可能性が高くなります。

また、実装に取り掛かるときは当該Issueに自分をアサインしてください(自分でできない場合は他メンバーに自分をアサインしてもらうようお願いしてください)。 自分が実装するという意思表示をすることで、作業がバッティングするのを防ぎます。

Issues

Issueを作成する前に、以下をご確認ください:

  • 重複を防ぐため、既に同様の内容のIssueが作成されていないか検索してから新しいIssueを作ってください。
  • Issueを質問に使わないでください。
    • Issueは、要望、提案、問題の報告にのみ使用してください。
    • 質問は、GitHub DiscussionsDiscordでお願いします。

PRの作成

PRを作成する前に、以下をご確認ください:

  • 可能であればタイトルに、以下で示すようなPRの種類が分かるキーワードをプリフィクスしてください。
    • fix / refactor / feat / enhance / perf / chore 等
    • また、PRの粒度が適切であることを確認してください。ひとつのPRに複数の種類の変更や関心を含めることは避けてください。
  • このPRによって解決されるIssueがある場合は、そのIssueへの参照を本文内に含めてください。
  • CHANGELOG.mdに変更点を追記してください。リファクタリングなど、利用者に影響を与えない変更についてはこの限りではありません。
  • この変更により新たに作成、もしくは更新すべきドキュメントがないか確認してください。
  • 機能追加やバグ修正をした場合は、可能であればテストケースを追加してください。
  • テスト、Lintが通っていることを予め確認してください。
    • npm run testnpm 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をマージすることで、予期せずパフォーマンスが悪化しないか
    • もっと効率的な方法は無いか?
  • テスト
    • 期待する振る舞いがテストで担保されているか?
    • 抜けやモレは無いか?
    • 異常系のチェックは出来ているか?