メインコンテンツへスキップ

Docusaurusへのコントリビューション

Docusaurusはオープンソースのドキュメンテーションをより簡単にする方法です。現在、これを用いているオープンソースのプロジェクトが多数あり、さらに多くのプロジェクトが計画されています。Docusaurusにコントリビューションすることに興味がある場合、この記事が貢献プロセスを明確にしてくれるでしょう。

Open Source Guidesウェブサイトには、オープンソースプロジェクトの実行方法とコントリビューション方法を学びたい個人、コミュニティ、企業向けの資料がまとめられています。オープンソースに慣れている人と新規参入者は、以下のガイドを特に役立つと感じるでしょう。

行動規範​

Facebookは、プロジェクト参加者が遵守することを期待する行動規範を採用しています。全文をお読みください。そうすれば、どのような行動が許され、許されないのかを理解できるでしょう。

取り組みを開始する​

Docusaurusにコントリビューションする方法には数多くあり、その多くはコーディングを必要としません。以下に、入門するためのアイデアをいくつか紹介します。

  • Docusaurusの使用を開始するだけです。 入門ガイドを参照してください。すべてが予想通りに機能しますか？そうでない場合は、私たちは常に改善策を探しています。問題を開いてお知らせください。
  • オープンな問題を調べます。回避策を提供したり、明確化を求めたり、ラベルを提案したりします。 問題のトリアージを支援します。
  • 修正したい問題が見つかったら、プルリクエストを開きます。 初心者向けの問題としてタグ付けされた問題から始めるのが良いでしょう。
  • Docusaurus ドキュメント を読んでください。もしも混乱したり、改善できる点があれば、ほとんどのドキュメントの下にある「このページを編集」をクリックすると、変更を行って提案するための GitHub のインターフェイスに行くことができます。
  • コミュニティの他の人が リクエストした機能 を参照し、あなたが取り組みたいものが見つかった場合は、プルリクエストを開くことを検討してください。

コントリビューションは大歓迎です。コントリビューションの計画にサポートが必要だと思う場合は、Twitter の @docusaurus にピン留めして、少しのサポートを求めていることを知らせてください。

​私たちの Discord チャンネルに参加する

#contributors チャンネル Discord では、Docusaurus の開発に関することをすべて議論できます。 #help-and-questions チャンネルで他のユーザーをサポートすることにより、大きな助けになることもできます。

​問題とプルリクエストをトリアージする

コードを書かなくてもプロジェクトに貢献できる素晴らしい方法は、問題やプルリクエストのトリアージを彼らがやってくるにしたがってサポートすることです。

  • 問題を解決するために必要な詳細がすべて提供されていないと思われる場合は、詳細情報の提供をお願いします。
  • 問題を分類するのに役立つ ラベル を提案しましょう。
  • 古くなったり、クローズする必要がある問題にフラグを立てます。
  • テストプランを尋ね、コードをレビューします。

​私たちの開発プロセス

Docusaurus は独自の真実として GitHub を使用しています。コアチームはそこで直接作業します。すべての変更は最初から公開されます。

すべてのプルリクエストは、継続的インテグレーションシステムである GitHub actions によって確認されます。ユニットテスト、エンドツーエンドテスト、パフォーマンステスト、スタイルテストなど、他にもたくさんあります。

​ブランチの編成

Docusaurus には main という 1 つのプライマリブランチがあり、プルリクエストで新機能を配信するために展開プレビューを使用したフィーチャーブランチを使用します。

​問題

新しい問題を開く 場合は、必ず問題テンプレートに入力してください。この手順は非常に重要です！ そうしないと、あなたの問題は適時に対処されなくなる可能性があります。このような事態が発生しても、深刻に受け止めないでください。テンプレートに必要なすべての情報を収集できたら、新しい問題を開くことをためらわないでください。

GitHub の Issue Tracker を質問に使用しないでください。 Docusaurus の使用方法に関して質問がある場合は、 サポートチャンネル を使用してください。私たちはあなたの質問に答えるために最善を尽くします。

​バグ

公的なバグには GitHub Issues を使用しています。問題を報告したい場合は、誰かがすでにそれについて問題を開いていないか確認してください。これが新しく報告されていないバグであることが確実な場合は、 バグレポート を送信できます。

  • 1 つの問題、1 つのバグ: 問題ごとに単一のバグを報告してください。
  • 再現手順の説明: 問題を再現する手順をすべて記載してください。バグレポートを読む人は、この手順に従って最小限の労力で問題を再現できる必要があります。

バグのみ修正する場合、プルリクエストをすぐに送信してもかまいませんが、修正内容の詳細を記載した問題を提出することをお勧めします。特定の修正は承認されない場合でも問題を追跡するのに役立ちます。

セキュリティバグ​

Facebookには、セキュリティバグの安全な公開に関するバウンティプログラムがあります。これを念頭に置いて、公開の問題を提出せず、そのページで説明されている手順に従ってください。

機能リクエスト​

新しい機能や拡張機能をリクエストしたいが、まだプルリクエストを開こうと考えていない場合は、詳細なRFC形式で、機能テンプレートを使用して問題を提出できます。または、Cannyボードを使用して、よりカジュアルな機能リクエストを作成し、RFCを提案する前に十分な支持を得ることができます。

提案​

既存の実装に重大でない変更を加える場合は、提案テンプレートを使用して問題を提出することをお勧めします。これにより、多大な労力を費やす前に、提案について合意することができます。このような種類の問題はまれです。

問題の引き受け​

Docusaurusコードベースの使用方法とコントリビューションプロセスについての理解を深めるのに役立つ初心者向けの課題のリストがあります。これは、作業に取り掛かるのに最適な場所です。

good first issue以外にも、次のラベルも注目に値します。

  • help wanted: 特定のドメインに関する専門知識がある場合は、これらの課題に取り組むことであなたの専門知識が活かされます。
  • status: accepting pr: コミュニティコントリビューターは、これらの課題を自由に引き受けることができます。

これらの課題に取り組みたい場合は、「この課題に取り組みたい」というメッセージを送信するだけで、問題を担当し、問題のステータスを「引き受け済み」に更新します。あなたが行方不明の場合、7日以内にプルリクエストを送信する必要があります。これにより、別の誰かに問題を委任できます。

または、問題を開くときに、「セルフサービス」のチェックボックスをクリックして、自分で問題に取り組みたいことを示すこともできます。これにより、問題が「引き受け済み」として表示されます。

開発​

ワンクリックでオンラインコントリビューション設定​

貢献には Gitpod（無料のオンライン、VS Code ライクの IDE）を使用できます。ワンクリックで作業スペース（Docusaurus 2 用）を起動して、自動で

  • docusaurus リポジトリをクローンします。
  • 依存関係をインストールします。
  • yarn start を実行します

すぐに貢献を開始できるようにします。

Open in Gitpod

新しい github.dev 機能を使用することもできます。ファイルを閲覧中にドメイン名を github.com から github.dev に変更すると、ブラウザーがオンラインエディターに変わります。すぐに変更を加えてプルリクエストを送信できます。

インストール​

  1. Yarn がインストールされていることを確認します。
  2. リポジトリをクローンした後、リポジトリのルートで yarn install を実行します。これにより、すべての依存関係がインストールされ、すべてのローカルパッケージがビルドされます。
  3. 開発サーバーを起動するには、yarn workspace website start を実行します。

コード規約​

  • 最も重要：周囲を見回してください。プロジェクトの他の部分で使用されているスタイルに合わせます。これには、フォーマット、ファイルの命名、コード内の命名、ドキュメント内の命名などが含まれます。
  • "魅力的"
  • ほとんどのスタイル上の問題を検出するために Prettier（フォーマッター）と ESLint（構文リンター）があります。ローカルで作業している場合、git コミットのたびに自動的にいくつかの問題を修正する必要があります。
  • ドキュメントの場合：80 文字で改行しないでください。ドキュメントを編集するときに、エディターがソフトラップするように設定します。

一般的にスタイルをあまり気にしないでください。メンテナーは、コードをレビューするときにそれらを修正するのに協力します。

プルリクエスト​

プルリクエストを開いてコードをアップストリームに貢献することにしたのですね。かなりの時間を費やしていただき、感謝しています。喜んで対応して PR を確認させていただきます。

初めてのプルリクエストに取り組んでいますか？この無料ビデオシリーズで方法を学ぶことができます。

GitHub でオープンソースプロジェクトに貢献する方法

プルリクエストを送信する際には、次のことを必ず行なってください。

  1. PR を小さく保ちます。小さいプルリクエスト（差分は約 300 行）は、レビューがはるかに容易でマージされる可能性が高くなります。PR には 1 つのことしか行わないようにします。そうでない場合は、分割します。
  2. わかりやすいタイトルを使用します。この コミットメッセージスタイル に従うことをお勧めします。
  3. 変更をテストします。プルリクエストの説明に テストプラン を記載します。
  4. CLA。まだの場合は、CLA に署名します。

すべてのプルリクエストは main ブランチに対してオープンする必要があります。

間違いを防止するために自動テストを実行する統合システムをたくさん用意しています。メンテナーはコードをレビューし、わかりやすい問題を修正します。これらのシステムの義務は、可能な限り雑務について心配させないようにすることです。手順に従うよりも、コードへの貢献のほうが重要ですが、チェックリストを完了すると確実に全員の時間を節約できます。

セマンティックコミットメッセージ​

コミットメッセージスタイルを少し変えるだけで、より良いプログラマーになれることを確認します。

フォーマット: <type>(<scope>): <subject>

<scope>は省略可能です。変更が1つまたは2つのパッケージに固有の場合は、スコープを追加することを検討してください。スコープは簡潔であると同時に認識可能なものでなければなりません。例: content-docs、theme-classic、core

さまざまなタイプのコミット

  • feat: エンドユーザー向けの新しいAPIまたは動作。
  • fix: エンドユーザー向けのバグ修正。
  • docs: リポジトリ内のウェブサイトまたは他のMarkdownドキュメントに対する変更。
  • refactor: 動作の差をもたらさない、実稼働コードへの変更。例: ファイルの分割、内部変数の変更、コードスタイルの改善など
  • test: 不足しているテストの追加、テストのリファクタ;実稼働コードの変更はありません。
  • chore: 依存関係のアップグレード、新しいバージョンのリリースなど。メンテナンス目的で定期的に行われる作業。
  • misc: 実稼働コードを変更せず、testまたはchoreでもないものすべて。例: GitHubのワークフローの更新。

ただし、PRタイトルにあまりストレスをかけないでください。あなたのPRはSquashマージされ、mainブランチへのコミットはPRのタイトルを取得するため、ブランチ内のコミットは意味的に名前を付ける必要はありません。メンテナーはPRタイトルを正しく取得するのに役立ちます。また、コミットメッセージのタイプと一致しないPRラベルシステムもあります。コードは慣習よりも重要です！

例

feat(core): allow overriding of webpack config
^--^^----^  ^------------^
|   |       |
|   |       +-> Summary in present tense. Use lower case not title case!
|   |
|   +-> The package(s) that this change affected.
|
+-------> Type: see above for the list we use.

バージョン付きドキュメント​

ドキュメントの変更のみを行う場合は、バージョン付きドキュメントを知っておく必要があります。

必要な場合を除き、versioned_docs/またはversioned_sidebars/内の自動生成ファイルは編集しないでください。たとえば、新機能に関する情報はバージョン付きドキュメントには記載しないでください。古いバージョンに対する編集は、ドキュメントの新バージョンには伝搬されません。

テストプラン​

優れたテストプランには、実行した正確なコマンドとその出力が含まれ、プルリクエストがUIを変更する場合はスクリーンショットまたはビデオが提供されます。APIを変更した場合は、ドキュメントを更新します。

テストは継続的インテグレーションシステムに組み込まれているため、常にローカルテストを実行する必要はありません。ただし、コードに大幅な変更を加えた場合は、PRの調子が確実に良いかどうかを確認するために、まずローカルで徹底的なテストを実行すると、あなたとメンテナーの両方の時間を節約できます。テストにはさまざまな種類があります。

  • ビルドと型チェック。コードベースにはTypeScriptを使用しており、コードの一貫性を確保し、明白なミスを早期に検出できます。
  • ユニットテスト。APIエンドポイントの動作のユニットテストには、Jestを使用します。ルートディレクトリでyarn testを実行してすべてのテストを実行するか、yarn test path/to/your/file.test.tsを実行して特定のテストを実行できます。
  • ドッグフーディング。当社ウェブサイト自体では、あらゆる潜在的な構成ケースを網羅しており、専用のテスト領域もあります。PRでウェブサイトの構成を更新することを恐れないでください。メンテナーが効果をプレビューするのに役立ちます。ウェブサイトの変更をマージして実稼働用にデプロイする必要があるかどうかは決定できます。
  • E2E テスト。最近の変更でコードのディストリビューションとインストールをシミュレートできます。ローカルで変更をテストするときも、ローカルでサードパーティーのテストを実施する方法に関するドキュメントを参照してください。

ライセンス​

Docusaurus に貢献することにより、あなたの貢献がその MIT ライセンスの下でライセンスされることに同意します。新しいファイルの先頭にこれをコピーして貼り付けてください。

/**
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 */

これは header/header ESLint ルールで自動的に修正することもできます。

貢献者ライセンス同意書 (CLA)​

プルリクエストを受け入れるには、CLA を提出していただく必要があります。これは一度だけ行う必要があるので、他の Facebook オープンソースプロジェクトでこれを行った場合は問題ありません。初めてのプルリクエストの提出の場合は、Facebook GitHub ボットが CLA フォームへのリンクを送信返信します。こちらで CLA の記入を完了することもできます。

CLA に署名すると、CLA ボットが自動的に PR のステータスを更新します。新しい PR を作成する必要はありません。

プルリクエストのマージには CLA が必要です。あなたの努力を高く評価しており、プルリクエストを送信した後も対応できず、レビューに戻って来ていただくまでお待ちするつもりですが、マージの準備ができていますが、CLA を提出していない、または著者からの応答がないプルリクエストは開設後 2 週間以内にクローズされます。CLA に関するご質問がございましたら、お気軽にお問い合わせください。

もしあなたの都合が悪くて PR がクローズされてしまっても、準備ができたら再オープンしてください！喜んでレビューし、完了までサポートし、最終的にはマージします。

重大な変更​

新しい重大な変更を追加する場合、プルリクエストでこのテンプレートに従ってください

### New breaking change here

- **Who does this affect**:
- **How to migrate**:
- **Why make this breaking change**:
- **Severity (number of people affected x effort)**:

次のステップ​

Docusaurus コアチームは、プルリクエストを監視します。上記のガイドラインに従って、プルリクエストの一貫性を維持してください。