The mod_cluster Project Documentation

Table of Contents

• Contributing
• Guidelines
• Building
• How does it actually work?
• Questions?
• License

Welcome to the new mod_cluster live documentation!

Contributing

How can I contribute?

• Get familiar with AsciiDoc.

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

• 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.

  • 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.

Building

The build uses Apache Maven.

[rhusar@ribera docs.modcluster.io]$ mvn verify
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Build Order:
[INFO]
[INFO] mod_cluster docs (parent)                                          [pom]
[INFO] mod_cluster docs: Documentation                                    [pom]
[INFO]
[INFO] -----------< org.jboss.mod_cluster:mod_cluster-docs-parent >------------
[INFO] Building mod_cluster docs (parent) 2.0.0.Final-SNAPSHOT            [1/2]
[INFO]   from pom.xml
[INFO] --------------------------------[ pom ]---------------------------------
[INFO]
[INFO] --- enforcer:3.4.1:enforce (enforce-java-version) @ mod_cluster-docs-parent ---
[INFO] Rule 0: org.apache.maven.enforcer.rules.BannedRepositories passed
[INFO] Rule 1: org.apache.maven.enforcer.rules.version.RequireJavaVersion passed
[INFO]
[INFO] --- enforcer:3.4.1:enforce (enforce-maven-version) @ mod_cluster-docs-parent ---
[INFO] Rule 0: org.apache.maven.enforcer.rules.version.RequireMavenVersion passed
[INFO]
[INFO] --- enforcer:3.4.1:enforce (enforce-https-repositories) @ mod_cluster-docs-parent ---
[INFO] Rule 0: org.apache.maven.enforcer.rules.BannedRepositories passed
[INFO]
[INFO] --- buildnumber:3.2.0:create (get-scm-revision) @ mod_cluster-docs-parent ---
[INFO] Executing: /bin/sh -c cd '/Users/rhusar/git/docs.modcluster.io' && 'git' 'rev-parse' '--verify' 'HEAD'
[INFO] Working directory: /Users/rhusar/git/docs.modcluster.io
[INFO] Storing buildNumber: 9917545bbd99d1c3457f5ede71cb4f42c8090405 at timestamp: 1708340454545
[INFO] Executing: /bin/sh -c cd '/Users/rhusar/git/docs.modcluster.io' && 'git' 'symbolic-ref' 'HEAD'
[INFO] Working directory: /Users/rhusar/git/docs.modcluster.io
[INFO] Storing scmBranch: main
[INFO]
[INFO] --- source:3.2.1:jar-no-fork (attach-sources) @ mod_cluster-docs-parent ---
[INFO]
[INFO] ---------------< org.jboss.mod_cluster:mod_cluster-docs >---------------
[INFO] Building mod_cluster docs: Documentation 2.0.0.Final-SNAPSHOT      [2/2]
[INFO]   from docs/pom.xml
[INFO] --------------------------------[ pom ]---------------------------------
[INFO]
[INFO] --- enforcer:3.4.1:enforce (enforce-java-version) @ mod_cluster-docs ---
[INFO] Rule 0: org.apache.maven.enforcer.rules.BannedRepositories passed
[INFO]
[INFO] --- enforcer:3.4.1:enforce (enforce-maven-version) @ mod_cluster-docs ---
[INFO]
[INFO] --- enforcer:3.4.1:enforce (enforce-https-repositories) @ mod_cluster-docs ---
[INFO] Rule 0: org.apache.maven.enforcer.rules.BannedRepositories passed
[INFO]
[INFO] --- buildnumber:3.2.0:create (get-scm-revision) @ mod_cluster-docs ---
[INFO]
[INFO] --- asciidoctor:2.2.6:process-asciidoc (output-pdf-user-guide) @ mod_cluster-docs ---
[INFO] Copying 6 resources to images
uri:classloader:/gems/prawn-svg-0.33.0/lib/prawn/svg/properties.rb:54: warning: `*' interpreted as argument prefix
uri:classloader:/gems/prawn-svg-0.33.0/lib/prawn/svg/ttf.rb:40: warning: assigned but unused variable - platform_specific_id
uri:classloader:/gems/prawn-svg-0.33.0/lib/prawn/svg/ttf.rb:35: warning: assigned but unused variable - format
uri:classloader:/META-INF/jruby.home/lib/ruby/stdlib/ostruct.rb:466: warning: OpenStruct#public_send accesses caller method's state and should not be aliased
uri:classloader:/META-INF/jruby.home/lib/ruby/stdlib/ostruct.rb:466: warning: OpenStruct#method accesses caller method's state and should not be aliased
[INFO] Converted /Users/rhusar/git/docs.modcluster.io/docs/src/main/asciidoc/index.adoc
[INFO]
[INFO] --- source:3.2.1:jar-no-fork (attach-sources) @ mod_cluster-docs ---
[INFO]
[INFO] --- asciidoctor:2.2.6:process-asciidoc (output-html-user-guide) @ mod_cluster-docs ---
[INFO] Copying 6 resources to images
[INFO] Copying 1524 resources to .
[INFO] Converted /Users/rhusar/git/docs.modcluster.io/docs/src/main/asciidoc/index.adoc
[INFO]
[INFO] --- asciidoctor:2.2.6:process-asciidoc (output-html-developer-resources) @ mod_cluster-docs ---
[INFO] Copying 5 resources to images
[INFO] Converted /Users/rhusar/git/docs.modcluster.io/docs/src/main/asciidoc/developer/q_a_webinar.adoc
[INFO] Converted /Users/rhusar/git/docs.modcluster.io/docs/src/main/asciidoc/developer/encrypting_connection.adoc
[INFO] Converted /Users/rhusar/git/docs.modcluster.io/docs/src/main/asciidoc/developer/node_conf.adoc
[INFO] Converted /Users/rhusar/git/docs.modcluster.io/docs/src/main/asciidoc/developer/ping_pong.adoc
[INFO] Converted /Users/rhusar/git/docs.modcluster.io/docs/src/main/asciidoc/developer/cluster_listener.adoc
[INFO] Converted /Users/rhusar/git/docs.modcluster.io/docs/src/main/asciidoc/developer/jbc_data_partitioning.adoc
[INFO] Converted /Users/rhusar/git/docs.modcluster.io/docs/src/main/asciidoc/developer/management_protocol.adoc
[INFO] Converted /Users/rhusar/git/docs.modcluster.io/docs/src/main/asciidoc/developer/reverse_extension.adoc
[INFO] Converted /Users/rhusar/git/docs.modcluster.io/docs/src/main/asciidoc/developer/hw_load_balancer.adoc
[INFO] Converted /Users/rhusar/git/docs.modcluster.io/docs/src/main/asciidoc/developer/version_1.3.1.adoc
[INFO] Converted /Users/rhusar/git/docs.modcluster.io/docs/src/main/asciidoc/developer/internals.adoc
[INFO] Converted /Users/rhusar/git/docs.modcluster.io/docs/src/main/asciidoc/developer/fedora24_25_update_testing.adoc
[INFO] Converted /Users/rhusar/git/docs.modcluster.io/docs/src/main/asciidoc/developer/info_rsp.adoc
[INFO] Converted /Users/rhusar/git/docs.modcluster.io/docs/src/main/asciidoc/developer/mod_proxy_forwarding.adoc
[INFO] Converted /Users/rhusar/git/docs.modcluster.io/docs/src/main/asciidoc/developer/index.adoc
[INFO] Converted /Users/rhusar/git/docs.modcluster.io/docs/src/main/asciidoc/developer/design.adoc
[INFO] Converted /Users/rhusar/git/docs.modcluster.io/docs/src/main/asciidoc/developer/node_balancers.adoc
[INFO] Converted /Users/rhusar/git/docs.modcluster.io/docs/src/main/asciidoc/developer/choosing_doc_platform.adoc
[INFO] Converted /Users/rhusar/git/docs.modcluster.io/docs/src/main/asciidoc/developer/as_integration.adoc
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary for mod_cluster docs (parent) 2.0.0.Final-SNAPSHOT:
[INFO]
[INFO] mod_cluster docs (parent) .......................... SUCCESS [  0.901 s]
[INFO] mod_cluster docs: Documentation .................... SUCCESS [ 30.077 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  31.114 s
[INFO] Finished at: 2024-02-19T12:01:24+01:00
[INFO] ------------------------------------------------------------------------

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