Skip to content

Latest commit

 

History

History
148 lines (130 loc) · 8.83 KB

README.adoc

File metadata and controls

148 lines (130 loc) · 8.83 KB
Raw

The mod_cluster Project Documentation

Table of Contents

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.