Documentation 2.0

Welcome to the new mod_cluster live documentation!

Contributing

How can I contribute?

• Learn AsciiDoc.

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

• Click 'Help us improve this section on GitHub!' at the top of each section.

• If using an IDE, fork and clone the repository locally and navigate to docs/src/main/asciidoc/ directory.

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

• Pull request will be quickly reviewed, merged and changes will be live almost instantly!

Guidelines

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

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

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

Building locally

The build uses Maven.

[rhusar@ribera docs.modcluster.io]$ mvn clean install
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Build Order:
[INFO]
[INFO] mod_cluster docs (parent)                                          [pom]
[INFO] mod_cluster: Documentation                                         [pom]
[INFO]
[INFO] -----------< org.jboss.mod_cluster:mod_cluster-docs-parent >------------
[INFO] Building mod_cluster docs (parent) 2.0.0.Alpha1-SNAPSHOT           [1/2]
[INFO] --------------------------------[ pom ]---------------------------------
[INFO]
[INFO] --- maven-clean-plugin:3.1.0:clean (default-clean) @ mod_cluster-docs-parent ---
[INFO]
[INFO] --- maven-enforcer-plugin:3.0.0-M2:enforce (enforce-java-version) @ mod_cluster-docs-parent ---
[INFO]
[INFO] --- maven-enforcer-plugin:3.0.0-M2:enforce (enforce-maven-version) @ mod_cluster-docs-parent ---
[INFO]
[INFO] --- buildnumber-maven-plugin:1.4: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: cd1648f9bcf15c0b18eb401bff899d6aff2619f8 at timestamp: 1540404397386
[INFO] Storing buildScmBranch: master
[INFO]
[INFO] --- maven-source-plugin:3.0.1:jar-no-fork (attach-sources) @ mod_cluster-docs-parent ---
[INFO]
[INFO] --- maven-install-plugin:2.5.2:install (default-install) @ mod_cluster-docs-parent ---
[INFO] Installing /Users/rhusar/git/docs.modcluster.io/pom.xml to /Users/rhusar/.m2/repository/org/jboss/mod_cluster/mod_cluster-docs-parent/2.0.0.Alpha1-SNAPSHOT/mod_cluster-docs-parent-2.0.0.Alpha1-SNAPSHOT.pom
[INFO]
[INFO] ---------------< org.jboss.mod_cluster:mod_cluster-docs >---------------
[INFO] Building mod_cluster: Documentation 2.0.0.Alpha1-SNAPSHOT          [2/2]
[INFO] --------------------------------[ pom ]---------------------------------
[INFO]
[INFO] --- maven-clean-plugin:3.1.0:clean (default-clean) @ mod_cluster-docs ---
[INFO] Deleting /Users/rhusar/git/docs.modcluster.io/docs/target
[INFO]
[INFO] --- maven-enforcer-plugin:3.0.0-M2:enforce (enforce-java-version) @ mod_cluster-docs ---
[INFO]
[INFO] --- maven-enforcer-plugin:3.0.0-M2:enforce (enforce-maven-version) @ mod_cluster-docs ---
[INFO]
[INFO] --- buildnumber-maven-plugin:1.4:create (get-scm-revision) @ mod_cluster-docs ---
[INFO]
[INFO] --- asciidoctor-maven-plugin:1.5.6:process-asciidoc (pdf) @ mod_cluster-docs ---
[INFO] AsciiDoc processing is skipped.
[INFO]
[INFO] --- maven-source-plugin:3.0.1:jar-no-fork (attach-sources) @ mod_cluster-docs ---
[INFO]
[INFO] --- asciidoctor-maven-plugin:1.5.6:process-asciidoc (output-html) @ mod_cluster-docs ---
[INFO] Using 'UTF-8' encoding to copy filtered resources.
[INFO] Copying 5 resources to images
[INFO] Copying 1 resource to .
[INFO] Rendered /Users/rhusar/git/docs.modcluster.io/docs/src/main/asciidoc/index.adoc
[INFO]
[INFO] --- maven-install-plugin:2.5.2:install (default-install) @ mod_cluster-docs ---
[INFO] Installing /Users/rhusar/git/docs.modcluster.io/docs/pom.xml to /Users/rhusar/.m2/repository/org/jboss/mod_cluster/mod_cluster-docs/2.0.0.Alpha1-SNAPSHOT/mod_cluster-docs-2.0.0.Alpha1-SNAPSHOT.pom
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] mod_cluster docs (parent) 2.0.0.Alpha1-SNAPSHOT .... SUCCESS [  1.035 s]
[INFO] mod_cluster: Documentation 2.0.0.Alpha1-SNAPSHOT ... SUCCESS [  3.612 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 4.798 s
[INFO] Finished at: 2018-10-24T20:06:41+02:00
[INFO] ------------------------------------------------------------------------

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

Inner Workings

How does it work?

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

2. Changes are committed (merged) by a mod_cluster committer to the master branch.

3. CI is notified by GitHub webhooks of the new HEAD revision.

4. CI builds (and tests) the documentation.

5. The job for master branch deploys the documentation.

6. CI is configured with $GITHUB_TOKEN to authenticate as a docs bot with permissions for modcluster/docs.modcluster.io repository. Only the changes are committed.

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

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

Travis CI configuration uses deploy github extension and is configured as:

sudo: false
dist: trusty
language: java
script: mvn clean install
matrix:
  include:
    - env: JDK_RELEASE='OracleJDK 8'
      jdk: oraclejdk8
      deploy:
        provider: pages
        skip-cleanup: true
        repo: modcluster/docs.modcluster.io
        local-dir: docs/target/generated-docs/
        target-branch: gh-pages
        keep-history: true
        github-token: $GITHUB_TOKEN
        committer-from-gh: true
        email: [email protected]
        allow-empty-commit: false
        verbose: true
        on:
          branch: master

Permissions/Token Setup

1. Login as https://github.com/modcluster-docs-bot

2. Go to Settings → Developer settings → Personal access tokens

3. Generate new token with repo permissions

4. Go to https://github.com/modcluster/docs.modcluster.io → Settings → Invite collaborators and grant modcluster-docs-bot write access (only needs the gh-pages branch).

5. Accept invitation

6. Add GITHUB_TOKEN to https://travis-ci.org/modcluster/docs.modcluster.io/settings

Questions?

https://lists.jboss.org/mailman/listinfo/mod_cluster-dev