Usage

You can use Logging Parent as follows:

  1. Add org.apache.logging:logging-parent:12.1.1 as a parent to your pom.xml

  2. You may need to add .mvn/jvm.config to your project. See this as an example.

  3. Check if ./mvnw verify succeeds, otherwise make necessary changes

  4. Copy and adapt the support files (.gitignore, .gitattributes, etc.)

  5. Create workflows using reusable workflows. See Reusable GitHub Actions workflows for more details.

  6. Copy and adapt Log4j Changelog files:

    • src/changelog/.<majorVersion>.x.x/.release-notes.adoc.ftl

    • src/changelog/.changelog.adoc.ftl

    • src/changelog/.index.adoc.ftl

  7. In order to create an Antora-based site:

    1. Copy the following files and adapt them:

      • antora-playbook.yaml

      • package.json

      • src/site/antora/antora.yml

      • src/site/antora/.antora.yml

      • src/site/antora/modules/ROOT/pages/release-notes.adoc

    2. Build the website using ./mvnw site

    3. Check out the website generated to target/site by pointing a browser to it

Website deployment

Using deploy-site-reusable.yaml reusable GitHub Actions workflow, you can automate the website deployments for staging and production environments.

Example: Logging Parent branching scheme

See how deploy-site.yaml of Logging Parent achieves that using the

<source-branch>-site-<environment>-out

branch naming convention:

Staging website

https://logging.staged.apache.org/logging-parent

Production website

https://logging.apache.org/logging-parent

Release staging website

https://logging.staged.apache.org/logging-parent-<version>

Branch main

Contains the sources (i.e., AsciiDoc files) to build the staging website.

Branch main-site-stg-out

Populated automatically by the workflow triggered for changes on main. It contains the contents (i.e., HTML files) of the the staging website. In short, CI builds main and copies the generated target/site to main-site-stg-out.

Branch main-site-pro

Contains the sources (i.e., AsciiDoc files) to build the the production website. It is manually populated by maintainers. For instance,

  • after a release, the release tag is merged to main-site-pro

  • when there are minor website fixes in main that can also go to the production website, they are cherry-picked onto the main-site-pro

  • when there are production-only website fixes, they are committed to main-site-pro

Branch main-site-pro-out

Populated automatically by the workflow triggered for changes on main-site-pro. It contains the contents (i.e., HTML files) of the production website. In short, CI builds main-site-pro and copies the generated target/site to main-site-pro-out.

Branch release/<version>

Contains the sources (i.e., AsciiDoc files) to build the release staging website. It is manually populated by the release manager during a release.

Branch release/<version>-site-stg-out

Populated automatically by the workflow triggered for changes on release/<version>. It contains the contents (i.e., HTML files) of the release staging website. In short, CI builds release/<version> and copies the generated target/site to release/<version>-site-stg-out.

Rationale

This branching scheme allows to

  • host multiple websites in a single repository

  • deploy staging websites of multiple releases in parallel

Example: Log4j website branching scheme

For instance, the following branching scheme is used for the Log4j project:

Table 1. Log4j branching scheme for website deployments

Description

Branch name

Log4j 2

Log4j 3

Staging website sources

2.x

main

Staging website contents

2.x-site-stg-out

main-site-stg-out

Production website sources

2.x-site-pro

main-site-pro

Production website contents

2.x-site-pro-out

main-site-pro-out

Release staging website sources

release/<version>

Release staging website contents

release/<version>-site-stg-out