Document the build lifecycle and troubleshooting

[ppkarwasz]

Summary

Adds two Antora documentation pages that explain what the Logging Parent POM adds to a Maven build, addressing the long-standing gap that features.adoc only lists bundled plugins.

• build-lifecycle.adoc: a phase-by-phase overview table plus sections on:
  • the checks (Maven & Java version, order-independent dependency resolution, code style, changelog validation, Error Prone, SpotBugs + FindSecBugs, license validation, BND baseline), each tagged with its phase and origin (this POM vs. the ASF Parent POM);
  • the generated artifacts (OSGi manifest, JPMS descriptor, ServiceLoader descriptor, CycloneDX SBOM, and the inherited META-INF/{LICENSE,NOTICE,DEPENDENCIES});
  • the POM transformations (CI-friendly ${revision} resolution and BOM flattening);
  • the opt-in profiles: build modifiers (release, coverage, apache.snapshots) and commands (changelog-release, distribution, deploy).
• troubleshooting.adoc: debugging recipes for the two checks that are hardest to diagnose:
  • the BND baseline API-compatibility check (how to read the delta report, the MICRO/MINOR/MAJOR fixes, and the rationale behind the package-versioning convention);
  • the requireUpperBoundDeps order-independent dependency resolution check (how to read the error and whether to pin, bump, or unpin).

Both troubleshooting recipes use real error output captured by reproducing the failures locally.

Both pages are wired into the site navigation under a new "Build" group.

Notes

• Website/docs only; no change to the released parent POM artifact, so no changelog entry is included.
• A site-lifecycle page is intentionally deferred for a follow-up; its references were removed from this change.

🤖 Generated with Claude Code

[ramanathan1504]

@ppkarwasz

I just have a few minor suggestions and questions for you to consider:

build-lifecycle.adoc

• Under === Code style: You mention setting a .gitattributes file. Since developers might not know exactly what rules to put in it, would it be worth adding a 1-2 line snippet they can copy, or a link to a standard Apache Logging .gitattributes reference file?

• Under === Changelog validation: You link to {logging-services-url}/xml/ns/#log4j-changelog. I assume {logging-services-url} is defined globally in the site's playbook, but just double-checking to make sure it won't render as broken text since it isn't defined in the header of this specific file!

• Under Optional lifecycle extensions > -Prelease: It notes that this profile "enforces that neither the project version nor any of its dependencies is a SNAPSHOT." You might want to quickly clarify if this applies strictly to external dependencies, as multi-module builds usually have SNAPSHOT versions of sibling modules during the build process (though Maven handles this transparently, so leaving it as-is is probably fine too).

troubleshooting.adoc

• Hardcoded Version Numbers: Throughout the file, you use concrete versions like 2.27.0-SNAPSHOT, 2.26.1, and 2.20.2. While this is good for readability because it perfectly matches the terminal output snippet, these specific numbers will eventually look outdated.

  • Suggestion: Should we replace them with generic placeholders (like <major>.<minor>.<patch> or x.y.z)? Alternatively, if we want to keep the concrete numbers for easier reading, maybe we just add a small note like: "Note: versions like 2.27.0 are used here purely as examples" so it ages better?

• Under === MINOR (Formatting consistency): In step 3, you use **not** (double asterisks), but you used *not* (single asterisks) in the MICRO section above. I recommend changing it to *not* just for AsciiDoc consistency.

• Under === MINOR (Step 2 - Changelog): Step 1 mentions bumping the <revision> property to a new minor version (e.g., 2.27.0-SNAPSHOT). Does the developer also need to create a new changelog directory like src/changelog/.2.27.x/ instead of the old patch one? If the log4j-changelog-maven-plugin expects the directory to match, it might be worth explicitly stating that they should create the new minor release directory here.

[ramanathan1504]

@ppkarwasz Changelog is missing right?

[ppkarwasz]

Hi @ramanathan1504, I addressed your remarks in 365865b

Changelog is missing right?

I don't think this kind of change needs a changelog: it does not touch the Maven artifact itself, only it documentation.

[ramanathan1504]

Hi @ramanathan1504, I addressed your remarks in 365865b

Changelog is missing right?

I don't think this kind of change needs a changelog: it does not touch the Maven artifact itself, only it documentation.

LGTM