Welcome to the new mod_cluster live documentation!
How can I contribute?
-
Learn AsciiDoc.
-
Open http:https://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!
-
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/masterbranch of this (docs.modcluster.io) repository.
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.
-
Changes are proposed in a pull request for
docs.modcluster.iorepository. -
Changes are committed (merged) by a mod_cluster committer to the master branch.
-
CI is notified by GitHub webhooks of the new HEAD revision.
-
CI builds (and tests) the documentation.
-
The job for master branch deploys the documentation.
-
CI is configured with
$GITHUB_TOKENto authenticate as a docs bot with permissions formodcluster/docs.modcluster.iorepository. Only the changes are committed. -
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-
Go to Settings → Developer settings → Personal access tokens
-
Generate new token with
repopermissions -
Go to https://github.com/modcluster/docs.modcluster.io → Settings → Invite collaborators and grant
modcluster-docs-botwrite access (only needs thegh-pagesbranch). -
Accept invitation
-
Add
GITHUB_TOKENto https://travis-ci.org/modcluster/docs.modcluster.io/settings