mod_cluster Project Documentation

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:

https://github.com/modcluster/docs.modcluster.io/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.

Questions?

https://github.com/modcluster/mod_cluster/discussions

License

• Apache License 2.0