[MS13] Automate website deployment

[vy]

Abstract: This PR completes the STF milestone 13 by implementing the infrastructure to auto-deploy the Log4j website from project sources. Due to reasons detailed below, the website support is migrated from AsciiDoctor Maven Plugin to Antora.

The problem description

Prior to this work, the website deployment for Log4j and its satellite projects (Log4j Kotlin, Log4j Tools, etc.) was a cumbersome process. One needed to checkout a particular Git reference, build the website (i.e., ./mvnw site), copy the generated content to a separate repository (e.g., Log4j sources are located in the logging-log4j2 repository, though the website content were located in the logging-log4j-site repository), and commit & push changes. This time consuming, intricate process had many drawbacks:

• In case of an emergency (e.g., a security vulnerability), the speed maintainers can update the website and the know-how required for it were far from ideal.
• Due to the complexity involved, users weren't contributing website improvements. Instead many users create a lengthy ticket complaining about a single letter typo. (See LOG4J2-3683 for a recent example.)

Deliverable 1: Migration to Antora

The website backend for Maven-based Logging Services projects are migrated from Asciidoctor Maven Plugin to the Antora with logging-parent version 11.0.0 release. To accommodate this, downstream needed to be extensively adjusted:

Warning: Some of the changes shared below contain also the upgrade of logging-parent to version 11.0.0, since Antora execution is centrally operated by that particular logging-parent version.

• Migrate 2.x website to Antora #2427
• Migrate 3.x website to Antora #2443
• Migrate Log4j Jakarta to Antora
• Migrate Log4j JMX GUI to Antora
• Migrate Log4j Kotlin to Antora
• Migrate Log4j Scala to Antora
• Migrate Log4j Tools to Antora
• Migrate Log4j Transform to Antora

Rationale

As we develop more with AsciiDoctor Maven Plugin, we soon started hitting several blockers. AsciiDoctor Maven Plugin beautifully renders "a web page" from an AsciiDoc file. But we quickly figured that this is a small piece of the puzzle while assembling "a website" composed of hundreds of pages linking to each other and supported by an intuitive navigation assistance. We implemented CSS/JavaScript workarounds for several of these shortcomings, and it occurred to us we are implementing a subset of Antora from scratch. As a result, the migration decision emerged naturally.

But why now? The automated website deployment relies on several assumptions and one of the pillar assumptions is how the website is built. We did not want to invest more into AsciiDoctor Maven Plugin given we know it doesn't fit the bill.

Implementation

Antora uses AsciiDoctor under the hood. How hard the migration can be? Right? Though the ride was pretty bumpy:

1. The old AsciiDoctor Maven Plugin plumbing in pom.xml (which is a substantial piece of code!) needed to be adapted for Antora.
2. AsciiDoctor Maven Plugin uses the Java implementation of AsciiDoctor. That is, the original AsciiDoctor software (i.e., the official AsciiDoc-to-HTML converter) is a Ruby application and for Java it is run using JRuby. On the other hand, Antora is JavaScript-based and uses Asciidoctor.js – a native JavaScript renderer for AsciiDoc. As a result, we needed to port the log4j-docgen-asciidoctor-extension module, implemented in Java, delivered in the STF milestone 9, to JavaScript.

Conclusion

We are happy with the end result. Antora has proven to be a better choice in terms of features it offers and the resultant Log4j website we generate from it.

Deliverable 2: Automated website deployment

Log4j and its satellite projects (Log4j Kotlin, Log4j Tools, etc.) are spread across multiple branches of multiple repositories. For instance, 2.x and main branches of the logging-log4j2 repository correspond to Log4j 2 and Log4j 3 releases, respectively. We needed a scheme to automatically generate 3 websites for each project:

1. The staging website (populated from the most recent changes in the source code)
2. The production website (populated from the most recent release website and any other custom changes)
3. The release website (created while drafting a release to be voted by the PMC)

All this infrastructure is implemented as a part of the logging-parent version 11.0.0 release:

• Release notes
• Automated website deployment support documentation
• Code changes

Usage

Since projects have already migrated to Antora earlier and automated website deployment facilities in the logging-parent takes care of the heavy work, projects need to only employ this in their CI:

• Logging Parent
• Log4j 2
• Log4j 3
• Log4j Jakarta
• Log4j JMX GUI
• Log4j Kotlin
• Log4j Samples (doesn't have a website!)
• Log4j Scala
• Log4j Tools
• Log4j Transform