Outline the recommended steps for making successful contributions to Quarkus documentation.
Prerequisites
Quarkus docs are built from source written using Asciidoc, a lightweight markup language.
We suggest you have the following materials nearby:
-
An editor or IDE that provides syntax highlighting and previews for asciidoc, either natively or using a plugin.
-
The Quarkus documentation reference for required syntax and other conventions.
Sources
-
Documentation for Quarkus core and most extensions is located in the
docs
directory of the Quarkus GitHub repository. -
Docs for Quarkiverse or other third-party extensions are pulled directly from those repositories.
Building and previewing Quarkus documentation
Asciidoc syntax highlighting and the preview provided by an IDE can be sufficient for minor documentation changes. For significant changes or any changes related to Quarkus configuration documentation, we recommend that you run the build and view the resulting output before submitting your changes for review.
The following will build all modules in the Quarkus repository (except test modules) and install them in your local maven repository with the 999-SNAPSHOT
version:
$ ./mvnw -DquicklyDocs
This will produce a few things:
-
Generated configuration properties documentation will be located in the
target/asciidoc/generated/config/
directory. -
Asciidoc output (html files) will be found in the
docs/target/generated-docs/
directory.
As you make additional changes, you can build the docs
module specifically to update the generated HTML:
$ ./mvnw -f docs clean install
If you change the configuration properties of an extension,
rebuild that extension first (to regenerate the associated config docs in target/asciidoc/generated/config/
),
and then rebuild the docs
module.
Creating pull requests for doc updates
Submit your proposed changes to the core Quarkus docs by creating a pull request against the main
branch of the Quarkus repository from your own repository fork.
Changes to docs for Quarkiverse or other third-party extensions should be submitted as pull requests in respective repository according to its contribution guide. |
Reviews for code and documentation have different (but overlapping) participants. To simplify collaborative review, either isolate changes to docs in their own PRs, or ensure that the PRs has a single, focused purpose. For example:
-
A single PR that adds a configuration option for an extension and updates related materials (how-to, reference) to explain the change.
-
A single PR for related changes to several docs, e.g. updates to ensure a term is used consistently, correcting a recurring error, or moving repeated content into a shared file.
-
If there are extensive code changes as well as documentation changes, make a separate PR for the documentation changes and indicate the relationship in the issue description.
Once created, the PR will be tagged automatically as something containing documentation changes.