How to contribute documentation
Quarkus ドキュメントへの貢献を成功させるための推奨ステップを概説します。
前提条件
Quarkus のドキュメントは、軽量マークアップ言語である Asciidoc を使用して、記述されたソースからビルドされます。
以下の資料を近くに置いておくことをお勧めします。
-
ネイティブまたはプラグインを使用して、asciidoc の構文の強調表示とプレビューを提供するエディターまたは IDE。
-
Quarkus ドキュメントリファレンス で、必要な構文およびその他の規約を確認することができます。
ソース
-
Quarkus のコアおよびほとんどのエクステンションのドキュメントは、 Quarkus GitHub リポジトリ の
docsディレクトリーにあります。 -
Quarkiverse やその他のサードパーティーのエクステンションのドキュメントは、それらのリポジトリから取得されます。
Quarkus ドキュメントのビルドおよびプレビュー
asciidoc の構文強調表示および IDE が提供するプレビューは、ドキュメントの変更が少ない場合は十分な可能性があります。重要な変更、または Quarkus の設定ドキュメントに関連する変更については、レビュー用に変更を送信する前に、ビルドを実行し、結果の出力を確認することが推奨されます。
以下は、Quarkusリポジトリにあるすべてのモジュール（テストモジュールを除く）をビルドし、 `999-SNAPSHOT`バージョンでローカルmavenリポジトリにインストールします:
$ ./mvnw -DquicklyDocsこれにより、次が生成されます。
-
target/asciidoc/generated/config/ディレクトリー内の設定プロパティーを記述する生成された Asciidoc ファイル。 -
`docs/target/generated-docs/`ディレクトリーの Asciidoc 出力 (html ファイル)。
変更を加えると、特に docs モジュールを再構築して、生成された HTML を更新できます。
#
$ ./mvnw -f docs clean installエクステンションの設定プロパティーを変更した場合には、最初にそのエクステンションをリビルドし (関連する設定ドキュメントを target/asciidoc/generated/config/ に再作成して)、 docs モジュールをリビルドしてください。
ドキュメント更新のためのプルリクエストの作成
Quarkus リポジトリーの main ブランチに対して、https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork[プルリクエストの作成] を行い、自身の リポジトリーのフォーク から Quarkus のコアドキュメントに変更案を提出します。
コードおよびドキュメントのレビューには、異なる (しかし重複する) 参加者がいます。共同レビューを簡単にするために、ドキュメントへの変更を独自の PR に分離するか、PR が確実に単一の焦点を絞った目的を持つようにください。たとえば、以下のようになります。
-
エクステンションの設定オプションを追加し、変更を説明するために関連資料 (ハウツー、リファレンス) を更新する単一の PR を作成します。
-
たとえば、用語の一貫性を確保するための更新、繰り返されるエラーの修正、繰り返される内容の共有ファイルへの移動など、複数の文書に対する関連する変更について、1 つの PR を作成します。
-
大規模なコードの変更とドキュメントの変更がある場合、ドキュメントの変更については別の PR を作成し、PR の説明でその関係を示してください。
一度作成された PR は、ドキュメントを含む何かが変更されると、自動的にタグ付けされます。
