Skip to content

Latest commit

 

History

History
60 lines (39 loc) · 2.79 KB

README.adoc

File metadata and controls

60 lines (39 loc) · 2.79 KB

mod_cluster Project Documentation CI

Are you here to read the mod_cluster documentation? Just head over to https://docs.modcluster.io/ right away.

If you’re here to contribute, welcome to the mod_cluster documentation repository!

Contributing

How can I contribute?

  • Get familiar with AsciiDoc.

  • Open https://docs.modcluster.io and locate section you want to contribute.

  • Click 'Improve this page – edit on GitHub.' at the top of each section.

  • Once finished editing, click 'Propose changes' which will open a new pull request.

    • Alternatively, if you prefer using an IDE, fork and clone the repository locally and head over to docs/src/main/asciidoc/ directory. Commit and propose changes as you normally would.

  • Pull request will be promptly reviewed by mod_cluster project maintainers, merged, and changes will be live almost instantly!

Guidelines

  • Documentation changes infrequently. To minimize the maintenance cost of multiple documentation versions, use wording similar to "Since version 1.3" to describe behavior changes across versions.

    • Documentation pertaining to legacy versions prior to 1.3 can be dropped from the current version as it remains archived in the legacy docs section.

  • Commit messages: you can describe changes you have done, or you could leave the default GitHub message which will just say "Update section.adoc".

  • Use shorter lines to make rebasing and editing from the web slightly easier, ideally a single sentence per line.

  • Documentation always resides in main branch of the upstream (modcluster/docs.modcluster.io) repository.

Issues

Issues can be reported using GitHub Issues:

Building

Building locally requires JDK 11 or newer installed. The build uses Apache Maven and provides Maven wrapper for ease of use:

./mvnw verify

Resulting files are located in the docs/target/generated-docs/ directory.

How does it actually work?

  1. Changes are proposed in a pull request for the docs.modcluster.io repository.

  2. GitHub Actions run CI to verify changes do not break the docs build.

  3. Changes are accepted and merged by a mod_cluster maintainer to the main branch.

  4. GitHub Actions detect the changes and run a maven build, push the changes into gh-pages branch of the upstream repository.

  5. GitHub Pages picks up the changes and deploys the website.

Note
 CNAME record is configured on the website pointing to GitHub servers.