vy opened a new issue, #2476: URL: https://github.com/apache/logging-log4j2/issues/2476
**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](https://issues.apache.org/jira/browse/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 Antora with `logging-parent` version `11.0.0` release. To accommodate this, downstream needed to be adjusted too: - #2427 - #2443 - [ ] 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. 1. 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](https://logging.apache.org/logging-parent/release-notes.html#release-notes-11-0-0) * [Automated website deployment support documentation](https://logging.staged.apache.org/logging-parent-11.0.0/usage.html#website) * [Code changes](/apache/logging-parent/compare/rel/10.6.0...stf-ms13) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
