This is an automated email from the ASF dual-hosted git repository.
github-actions[bot] pushed a commit to branch main-site-pro-out
in repository https://gitbox.apache.org/repos/asf/logging-parent.git
The following commit(s) were added to refs/heads/main-site-pro-out by this push:
new e54b45b Add website content generated from
`ba2e41f07dcc362a00fd0d76ea544aa8957cfbc5`
e54b45b is described below
commit e54b45bab40822e02af75d8ca86af39c68307f05
Author: ASF Logging Services RM <[email protected]>
AuthorDate: Fri Jul 24 16:08:54 2026 +0000
Add website content generated from
`ba2e41f07dcc362a00fd0d76ea544aa8957cfbc5`
---
_/css/site.css | 2 +-
build-lifecycle.html | 893 +++++++++++++++++++++++++++++++++++
features.html | 12 +
index.html | 12 +
release-instructions-project.html | 12 +
release-instructions-xml-schema.html | 12 +
release-notes.html | 12 +
release-review-instructions.html | 12 +
sitemap.xml | 24 +-
troubleshooting.html | 394 ++++++++++++++++
usage.html | 12 +
workflows.html | 12 +
12 files changed, 1400 insertions(+), 9 deletions(-)
diff --git a/_/css/site.css b/_/css/site.css
index 980f8b4..13d385f 100644
--- a/_/css/site.css
+++ b/_/css/site.css
@@ -1,3 +1,3 @@
-@font-face{font-family:Roboto;font-style:normal;font-weight:400;src:url(../font/roboto-latin-400-normal.woff2)
format("woff2"),url(../font/roboto-latin-400-normal.woff)
format("woff");unicode-range:U+00??,U+0131,U+0152-0153,U+02bb-02bc,U+02c6,U+02da,U+02dc,U+2000-206f,U+2074,U+20ac,U+2122,U+2191,U+2193,U+2212,U+2215,U+feff,U+fffd}@font-face{font-family:Roboto;font-style:normal;font-weight:400;src:url(../font/roboto-cyrillic-400-normal.woff2)
format("woff2");unicode-range:U+0301,U+0400-04 [...]
+@font-face{font-family:Roboto;font-style:normal;font-weight:400;src:url(../font/roboto-latin-400-normal.woff2)
format("woff2"),url(../font/roboto-latin-400-normal.woff)
format("woff");unicode-range:U+00??,U+0131,U+0152-0153,U+02bb-02bc,U+02c6,U+02da,U+02dc,U+2000-206f,U+2074,U+20ac,U+2122,U+2191,U+2193,U+2212,U+2215,U+feff,U+fffd}@font-face{font-family:Roboto;font-style:normal;font-weight:400;src:url(../font/roboto-cyrillic-400-normal.woff2)
format("woff2");unicode-range:U+0301,U+0400-04 [...]
/*! Adapted from the GitHub style by Vasily Polovnyov <[email protected]>
*/.hljs-comment,.hljs-quote{color:#998;font-style:italic}.hljs-keyword,.hljs-selector-tag,.hljs-subst{color:#333;font-weight:600}.hljs-literal,.hljs-number,.hljs-tag
.hljs-attr,.hljs-template-variable,.hljs-variable{color:teal}.hljs-doctag,.hljs-string{color:#d14}.hljs-section,.hljs-selector-id,.hljs-title{color:#900;font-weight:600}.hljs-subst{font-weight:400}.hljs-class
.hljs-title,.hljs-type{color:#458;font-wei [...]
\ No newline at end of file
diff --git a/build-lifecycle.html b/build-lifecycle.html
new file mode 100644
index 0000000..06fdf57
--- /dev/null
+++ b/build-lifecycle.html
@@ -0,0 +1,893 @@
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <meta charset="utf-8">
+ <meta name="viewport" content="width=device-width,initial-scale=1">
+ <title>Build lifecycle :: Apache Logging Parent</title>
+ <link rel="canonical"
href="https://logging.apache.org/logging-parent/build-lifecycle.html";>
+ <meta name="generator" content="Antora 3.2.0-alpha.8">
+<link rel="stylesheet" href="./_/css/site.css">
+<link rel="icon" href="./_/../_images/favicon.ico" type="image/x-icon">
+<!-- `@asciidoctor/tabs` extension styles -->
+<link rel="stylesheet" href="./_/css/vendor/tabs.css">
+<style>
+ /* Swap colors of `IMPORTANT` and `WARNING` blocks */
+ .doc .admonitionblock.important .icon { background-color: #f70; }
+ .doc .admonitionblock.warning .icon { background-color: #e40046; }
+ /* Default `h4`, `h5`, and `h6` are smaller than the normal text, fix header
font sizing: */
+ .doc h1 { font-size: 1.9rem; }
+ .doc h2 { font-size: 1.7rem; }
+ .doc h3 { font-size: 1.5rem; font-weight: 400; }
+ .doc h4 { font-size: 1.3rem; font-weight: 500; }
+ .doc h5 { font-size: 1.1rem; font-weight: 500; text-decoration: underline; }
+ .doc h6 { font-size: 0.9rem; font-weight: 500; text-decoration: underline; }
+ /* Default `code`, `pre`, and `.colist` (source code annotations) fonts are
too big, adjust them: */
+ .doc .colist>table code, .doc p code, .doc thead code { font-size: 0.8em; }
+ .doc pre { font-size: 0.7rem; }
+ .doc .colist { font-size: 0.75rem; }
+ /* Make links more visible: */
+ .doc a { text-decoration: underline; }
+ .doc a code { text-decoration: underline; color: #1565c0; }
+ /* Tab header fonts aren't rendered good, adjusting the font weight: */
+ .tablist > ul li { font-weight: 500; }
+ /* `page-toclevels` greater than 4 are not supported by Antora UI, patching
it: */
+ .toc .toc-menu li[data-level="4"] a {
+ padding-left: 2.75rem;
+ }
+ /* Replace the default highlight.js color for strings from red
(unnecessarily signaling something negative) to green: */
+ .hljs-string {
+ color: #0f8532;
+ }
+</style>
+ </head>
+ <body class="article">
+<header class="header">
+ <nav class="navbar">
+ <div class="navbar-brand">
+ <span class="navbar-item title">Apache Logging Parent</span>
+ </div>
+ <div id="topbar-nav" class="navbar-menu">
+ <div class="navbar-end">
+ <a class="navbar-item" href="https://logging.apache.org";>a subproject
of <strong>Apache Logging Services</strong></a>
+ </div>
+ </div>
+ </nav>
+</header>
+<div class="body">
+<div class="nav-container" data-component="ROOT" data-version="">
+ <aside class="nav">
+ <div class="panels">
+<div class="nav-panel-menu is-active" data-panel="menu">
+ <nav class="nav-menu">
+ <button class="nav-menu-toggle" aria-label="Toggle expand/collapse all"
style="display: none"></button>
+ <h3 class="title"><a href="index.html">Home</a></h3>
+<ul class="nav-list">
+ <li class="nav-item" data-depth="0">
+<ul class="nav-list">
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="features.html">Features</a>
+ </li>
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="usage.html">Usage</a>
+ </li>
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="release-notes.html">Release notes</a>
+ </li>
+</ul>
+ </li>
+ <li class="nav-item" data-depth="0">
+ <button class="nav-item-toggle"></button>
+ <span class="nav-text">Build</span>
+<ul class="nav-list">
+ <li class="nav-item is-current-page" data-depth="1">
+ <a class="nav-link" href="build-lifecycle.html">Build lifecycle</a>
+ </li>
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="troubleshooting.html">Troubleshooting</a>
+ </li>
+</ul>
+ </li>
+ <li class="nav-item" data-depth="0">
+ <button class="nav-item-toggle"></button>
+ <span class="nav-text">Release support</span>
+<ul class="nav-list">
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="release-review-instructions.html">Project
release review instructions</a>
+ </li>
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="release-instructions-project.html">Project
release instructions</a>
+ </li>
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="release-instructions-xml-schema.html">XML schema
release instructions</a>
+ </li>
+</ul>
+ </li>
+</ul>
+ </nav>
+</div>
+ </div>
+ </aside>
+</div>
+<main class="article">
+<div class="toolbar" role="navigation">
+<button class="nav-toggle"></button>
+ <a href="index.html" class="home-link"></a>
+<nav class="breadcrumbs" aria-label="breadcrumbs">
+ <ul>
+ <li><a href="index.html">Home</a></li>
+ <li>Build</li>
+ <li><a href="build-lifecycle.html">Build lifecycle</a></li>
+ </ul>
+</nav>
+<div class="edit-this-page"><a
href="https://github.com/apache/logging-parent/edit/main/src/site/antora/modules/ROOT/pages/build-lifecycle.adoc";>Edit
this Page</a></div>
+</div>
+ <div class="content">
+<aside class="toc sidebar" data-title="Contents" data-levels="2">
+ <div class="toc-menu"></div>
+</aside>
+<article class="doc">
+<h1 class="page">Build lifecycle</h1>
+<div id="preamble">
+<div class="sectionbody">
+<div class="paragraph">
+<p>Logging Parent extends the standard Maven <em>default</em> (build)
lifecycle that runs on a plain</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-bash hljs"
data-lang="bash">./mvnw verify</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>with three kinds of additions:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><a href="#checks">Additional checks</a> that fail the build when a rule is
violated,</p>
+</li>
+<li>
+<p><a href="#artifacts">Additional generated artifacts</a> that are generated
and attached or embedded into your JARs, and</p>
+</li>
+<li>
+<p><a href="#transformations">Artifact transformations</a> applied to the POM
before it is published.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Some of these additions come from Logging Parent itself, some are inherited
from the
+<a href="https://maven.apache.org/pom/asf/";>ASF Parent POM</a>, and some are
activated only when a particular <em>activator file</em> is present in your
project.
+Each origin is called out below.</p>
+</div>
+<div class="paragraph">
+<p>Beyond a plain <code>./mvnw verify</code>, the parent also offers two
opt-in mechanisms:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><a href="#optional-extensions">Optional lifecycle extensions</a> that you
enable on the command line to modify a build, and</p>
+</li>
+<li>
+<p><a href="#commands">Additional commands</a> whose default goal performs a
single task on its own.</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="phase-map"><a class="anchor" href="#phase-map"></a>Overview</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The following table maps each addition to the Maven phase it binds to.
+Everything listed here is triggered by a plain <code>./mvnw verify</code>,
unless it is marked as conditional on an activator file.</p>
+</div>
+<table class="tableblock frame-all grid-all stretch">
+<colgroup>
+<col style="width: 22.2222%;">
+<col style="width: 22.2222%;">
+<col style="width: 55.5556%;">
+</colgroup>
+<thead>
+<tr>
+<th class="tableblock halign-left valign-top">Phase</th>
+<th class="tableblock halign-left valign-top">Origin</th>
+<th class="tableblock halign-left valign-top">Additions</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>validate</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a
href="https://maven.apache.org/pom/asf/";>ASF Parent POM</a></p></td>
+<td class="tableblock halign-left valign-top"><div class="content"><div
class="ulist">
+<ul>
+<li>
+<p><a href="#check-build-environment">Maven & Java version</a></p>
+</li>
+</ul>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>validate</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Logging
Parent</p></td>
+<td class="tableblock halign-left valign-top"><div class="content"><div
class="ulist">
+<ul>
+<li>
+<p><a href="#check-dependency-convergence">Order-independent dependency
resolution</a></p>
+</li>
+<li>
+<p><a href="#check-code-style">Code style</a> <em>(no wildcard
imports)</em></p>
+</li>
+<li>
+<p><a href="#check-changelog">Changelog validation</a></p>
+</li>
+</ul>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>generate-resources</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a
href="https://maven.apache.org/pom/asf/";>ASF Parent POM</a></p></td>
+<td class="tableblock halign-left valign-top"><div class="content"><div
class="ulist">
+<ul>
+<li>
+<p><a href="#artifacts-asf">Embedded LICENSE, NOTICE, and DEPENDENCIES</a></p>
+</li>
+</ul>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>process-resources</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Logging
Parent</p></td>
+<td class="tableblock halign-left valign-top"><div class="content"><div
class="ulist">
+<ul>
+<li>
+<p><a href="#transformations-pom">POM flattening</a></p>
+</li>
+</ul>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>compile</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Logging
Parent</p></td>
+<td class="tableblock halign-left valign-top"><div class="content"><div
class="ulist">
+<ul>
+<li>
+<p><a href="#check-static-analysis">Static analysis</a>
<em>(ErrorProne)</em></p>
+</li>
+</ul>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>process-classes</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Logging
Parent</p></td>
+<td class="tableblock halign-left valign-top"><div class="content"><div
class="ulist">
+<ul>
+<li>
+<p><a href="#artifacts-osgi">OSGi manifest</a></p>
+</li>
+<li>
+<p><a href="#artifacts-jpms">JPMS module descriptor</a></p>
+</li>
+<li>
+<p><a href="#artifacts-services">ServiceLoader descriptor</a></p>
+</li>
+</ul>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>package</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Logging
Parent</p></td>
+<td class="tableblock halign-left valign-top"><div class="content"><div
class="ulist">
+<ul>
+<li>
+<p><a href="#artifacts-sbom">CycloneDX SBOM</a></p>
+</li>
+</ul>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>verify</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Logging
Parent</p></td>
+<td class="tableblock halign-left valign-top"><div class="content"><div
class="ulist">
+<ul>
+<li>
+<p><a href="#check-code-style">Code style</a> (Spotless)</p>
+</li>
+<li>
+<p><a href="#check-license">License validation</a></p>
+</li>
+<li>
+<p><a href="#check-static-analysis">Static analysis</a> <em>(SpotBugs +
FindSecBugs)</em></p>
+</li>
+<li>
+<p><a href="#check-api-compatibility">API compatibility (BND baseline)</a></p>
+</li>
+</ul>
+</div></div></td>
+</tr>
+</tbody>
+</table>
+</div>
+</div>
+<div class="sect1">
+<h2 id="checks"><a class="anchor" href="#checks"></a>Additional checks</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The checks below run automatically during <code>./mvnw verify</code>.
+The trickier ones link to a debugging recipe in <a href="troubleshooting.html"
class="xref page">Troubleshooting</a>.</p>
+</div>
+<div class="sect2">
+<h3 id="check-build-environment"><a class="anchor"
href="#check-build-environment"></a>Maven & Java version</h3>
+<div class="paragraph">
+<p><em>Phase:</em> <code>validate</code>.
+<em>Enforced by the <a href="https://maven.apache.org/pom/asf/";>ASF Parent
POM</a>.</em></p>
+</div>
+<div class="paragraph">
+<p>To build an Apache Logging Services project you need:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>a <strong>JDK 17</strong> (the build pins the major version
<code>17</code>, not a later one), and</p>
+</li>
+<li>
+<p><strong>Maven 3.8.1 or later</strong>, most conveniently through the
bundled Maven Wrapper (<code>./mvnw</code>).</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Both requirements are checked by the <code>maven-enforcer-plugin</code>
inherited from the ASF Parent POM, through its <code>requireJavaVersion</code>
and <code>requireMavenVersion</code> rules.
+These rules can be modified using the properties below:</p>
+</div>
+<table class="tableblock frame-all grid-all stretch">
+<colgroup>
+<col style="width: 33.3333%;">
+<col style="width: 50%;">
+<col style="width: 16.6667%;">
+</colgroup>
+<thead>
+<tr>
+<th class="tableblock halign-left valign-top">Property</th>
+<th class="tableblock halign-left valign-top">Controls</th>
+<th class="tableblock halign-left valign-top">Default</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>minimalJavaBuildVersion</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Range of
JDK versions allowed to run the build</p></td>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>[17,18)</code></p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>minimalMavenBuildVersion</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Range of
Maven versions allowed to run the build</p></td>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>3.8.1</code></p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>maven.compiler.release</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Java
bytecode level the sources are compiled to</p></td>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>8</code></p></td>
+</tr>
+</tbody>
+</table>
+<div class="paragraph">
+<p>Although most artifacts still target Java 8 bytecode (through the
<code>javac --release 8</code> flag), JDK 17 is required to run the Maven
plugins in use and to keep builds reproducible.
+Bytecode generation can differ between JDK major versions, so pinning a single
one keeps the output byte-for-byte stable.</p>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>JDK 17 also requires the <code>--add-exports</code> and
<code>--add-opens</code> flags declared in <code>.mvn/jvm.config</code>, needed
by tools that reach into JDK compiler internals (such as Error Prone).
+See <a href="usage.html" class="xref page">Usage</a>.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+<div class="paragraph">
+<p>Some projects (currently only Log4j) additionally run their test suites
against a real <strong>JDK 8</strong> through
+<a
href="https://maven.apache.org/guides/mini/guide-using-toolchains.html";>Maven
Toolchains</a>
+in CI.
+This proves runtime compatibility with the Java 8 platform, beyond the
bytecode and API-surface guarantees that <code>--release 8</code> provides on
its own.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="check-dependency-convergence"><a class="anchor"
href="#check-dependency-convergence"></a>Order-independent dependency
resolution</h3>
+<div class="paragraph">
+<p><em>Phase:</em> <code>validate</code>.</p>
+</div>
+<div class="paragraph">
+<p>Maven’s default conflict <em>mediation</em> (nearest-wins, ties
broken by declaration order) can resolve a dependency to a version
<em>lower</em> than some transitive dependency requires, and the outcome can
shift when dependencies are reordered.
+The <code>maven-enforcer-plugin</code> <code>requireUpperBoundDeps</code> rule
forbids this: it fails whenever a resolved version is lower than the highest
one required across the graph.</p>
+</div>
+<div class="paragraph">
+<p>The fix is to pin that dependency to at least the highest required version,
making resolution order-independent.
+See <a href="troubleshooting.html#require-upper-bound-deps" class="xref
page">the Order-independent dependency resolution recipe</a> for how to read
the error and adjust the pin.</p>
+</div>
+<div class="admonitionblock important">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-important" title="Important"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>Pinning a transitive dependency in your
<code><dependencyManagement></code> only affects <em>your</em> build.
+It has <strong>no</strong> influence on the versions resolved by downstream
consumers of your artifacts.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+</div>
+<div class="sect2">
+<h3 id="check-code-style"><a class="anchor" href="#check-code-style"></a>Code
style</h3>
+<div class="paragraph">
+<p>Code style is enforced by the <code>spotless-maven-plugin</code> in the
<code>verify</code> phase, with one exception: the ban on wildcard imports is a
<code>maven-enforcer-plugin</code> rule that runs earlier, in the
<code>validate</code> phase.
+The following rules apply:</p>
+</div>
+<div class="dlist">
+<dl>
+<dt class="hdlist1">All files</dt>
+<dd>
+<div class="paragraph">
+<p>Line endings are normalized to UNIX (<code>LF</code>) and the ASF license
header is required.
+Set a <a
href="https://git-scm.com/docs/gitattributes";><code>.gitattributes</code>
file</a> so that Git checks files out with <code>LF</code> on every platform.
+For example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-gitattributes hljs"
data-lang="gitattributes">*.properties text lf
+*.java text lf
+*.yaml text lf
+*.yml text lf
+*.xml text lf
+# Only this file needs to have CRLF line endings
+/mvnw.cmd text crlf</code></pre>
+</div>
+</div>
+</dd>
+<dt class="hdlist1">Java</dt>
+<dd>
+<div class="paragraph">
+<p>Sources follow the
+<a href="https://github.com/palantir/palantir-java-format";>Palantir Java
format</a>, and imports must be explicit (wildcard imports are banned).</p>
+</div>
+</dd>
+<dt class="hdlist1">XML, POM, <code>.properties</code> & YAML</dt>
+<dd>
+<div class="paragraph">
+<p><code>pom.xml</code> is sorted with the Spotless <a
href="https://github.com/Ekryd/sortpom";>sortPom</a> step; XML and YAML files
also have trailing whitespace trimmed and a final newline enforced.</p>
+</div>
+</dd>
+</dl>
+</div>
+<div class="paragraph">
+<p>Most violations are fixed automatically by:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-bash hljs"
data-lang="bash">./mvnw spotless:apply</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Anything the formatter cannot fix must be corrected by hand.</p>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>The Spotless configuration must stay in sync with the project’s
<code>.editorconfig</code>.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+</div>
+<div class="sect2">
+<h3 id="check-changelog"><a class="anchor"
href="#check-changelog"></a>Changelog validation</h3>
+<div class="paragraph">
+<p><em>Phase:</em> <code>validate</code>.
+<em>Activated by <code>src/changelog/</code>.</em></p>
+</div>
+<div class="paragraph">
+<p>Apache Logging Services projects track their release notes as individual
XML files under <code>src/changelog/</code>, managed by the <a
href="https://github.com/apache/logging-log4j-tools/tree/main/log4j-changelog-maven-plugin";><code>log4j-changelog-maven-plugin</code></a>.
+When that directory is present, the <code>xml-maven-plugin</code> validates
every entry against the Log4j Changelog schema, so a malformed entry fails the
build early instead of breaking release-note generation later.</p>
+</div>
+<div class="paragraph">
+<p>The schema is documented on the <a
href="https://logging.apache.org/xml/ns/#log4j-changelog";>Log4j XML schema
page</a>.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="check-static-analysis"><a class="anchor"
href="#check-static-analysis"></a>Static analysis</h3>
+<div class="paragraph">
+<p>Two static analysis tools scan the code on every build.</p>
+</div>
+<div class="dlist">
+<dl>
+<dt class="hdlist1">Error Prone</dt>
+<dd>
+<div class="paragraph">
+<p><em>Phase:</em> <code>compile</code>.
+Bundled into the <code>maven-compiler-plugin</code> (alongside
<code>-Xlint:all</code>), it catches common Java mistakes as the code compiles.
+Its checks are fixed by Logging Parent and are not configurable per
project.</p>
+</div>
+</dd>
+<dt class="hdlist1">SpotBugs + FindSecBugs</dt>
+<dd>
+<div class="paragraph">
+<p><em>Phase:</em> <code>verify</code>.
+The <code>spotbugs-maven-plugin</code> runs SpotBugs together with the <a
href="https://find-sec-bugs.github.io/";>FindSecBugs</a> plugin for
security-oriented bug patterns.
+False positives can be suppressed by adding a
<code>spotbugs-exclude.xml</code> file to the project root; its presence alone
activates the exclusion filter.</p>
+</div>
+</dd>
+</dl>
+</div>
+</div>
+<div class="sect2">
+<h3 id="check-license"><a class="anchor" href="#check-license"></a>License
validation</h3>
+<div class="paragraph">
+<p><em>Phase:</em> <code>verify</code>.</p>
+</div>
+<div class="paragraph">
+<p>The <a
href="https://creadur.apache.org/rat";><code>apache-rat-plugin</code></a>
verifies that the project complies with the
+<a href="https://www.apache.org/legal/src-headers.html";>ASF Source Header and
Copyright Notice Policy</a>, failing the build when a file is missing the
required ASF license header.</p>
+</div>
+<div class="paragraph">
+<p>Files that legitimately cannot carry a header or have been exempted from
carrying one have been added to an exclude list.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="check-api-compatibility"><a class="anchor"
href="#check-api-compatibility"></a>API compatibility</h3>
+<div class="paragraph">
+<p><em>Phase:</em> <code>verify</code>.</p>
+</div>
+<div class="paragraph">
+<p>Public APIs must not change without an <strong>explicit</strong> version
bump.
+The <code>bnd-baseline-maven-plugin</code> compares each module’s
exported packages against their last release and enforces <a
href="https://docs.osgi.org/whitepaper/semantic-versioning/";>OSGi semantic
versioning</a>: a backward-compatible addition needs a <em>minor</em>
increment, a breaking change a <em>major</em> one, and an internal-only fix a
<em>micro</em> one.
+Package versions are declared with the <code>@Version</code> annotation in
each package’s <code>package-info.java</code>.</p>
+</div>
+<div class="paragraph">
+<p>When a change is not matched by the right increment, the build fails with a
table reporting the detected <em>delta</em> (<code>MICRO</code>,
<code>MINOR</code>, or <code>MAJOR</code>) and the version the plugin suggests.
+The rules for choosing the increment, and how to resolve such a failure, are
explained in <a href="troubleshooting.html#bnd-baseline" class="xref page">the
API compatibility recipe</a>.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="artifacts"><a class="anchor" href="#artifacts"></a>Additional
generated artifacts</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Beyond the main JAR, the build attaches or embeds the following.</p>
+</div>
+<div class="sect2">
+<h3 id="artifacts-osgi"><a class="anchor" href="#artifacts-osgi"></a>OSGi
manifest</h3>
+<div class="paragraph">
+<p><em>Phase:</em> <code>process-classes</code>.</p>
+</div>
+<div class="paragraph">
+<p>The <code>bnd-maven-plugin</code> generates an OSGi
<code>META-INF/MANIFEST.MF</code> and hands it to the
<code>maven-jar-plugin</code>, which packages it instead of its own default
manifest.
+BND derives the manifest from the compiled bytecode:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>Bundle-SymbolicName</code> is computed from the <code>groupId</code>
and <code>artifactId</code>;</p>
+</li>
+<li>
+<p><code>Export-Package</code> lists the packages annotated with
<code>org.osgi.annotation.bundle.Export</code> in their
<code>package-info.java</code>;</p>
+</li>
+<li>
+<p><code>Import-Package</code> is inferred from the packages the code actually
references.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>This automatic inference is correct in the vast majority of cases, but a
few situations must be declared explicitly, for example an <em>optional</em>
dependency, whose import BND marks as mandatory unless told otherwise.
+Such cases can be tuned through the following properties, without redefining
the whole BND configuration:</p>
+</div>
+<table class="tableblock frame-all grid-all stretch">
+<colgroup>
+<col style="width: 25%;">
+<col style="width: 50%;">
+<col style="width: 25%;">
+</colgroup>
+<thead>
+<tr>
+<th class="tableblock halign-left valign-top">Property</th>
+<th class="tableblock halign-left valign-top">Purpose</th>
+<th class="tableblock halign-left valign-top">Default</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>bnd-extra-package-options</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Extra
<code>Import-Package</code> instructions.</p></td>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><em>(empty)</em></p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>bnd-bundle-symbolicname</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Override
the computed <code>Bundle-SymbolicName</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">derived
from <code>groupId</code> and <code>artifactId</code></p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>bnd-multi-release</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Value of
the <code>Multi-Release</code> manifest header</p></td>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>false</code></p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>bnd-extra-config</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Arbitrary
extra BND instructions, appended last.</p></td>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><em>(empty)</em></p></td>
+</tr>
+</tbody>
+</table>
+<div class="paragraph">
+<p>For the full set of <code>bnd-*</code> properties and worked examples, see
<a href="usage.html" class="xref page">Usage</a>.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="artifacts-jpms"><a class="anchor" href="#artifacts-jpms"></a>JPMS
module descriptor</h3>
+<div class="paragraph">
+<p><em>Phase:</em> <code>process-classes</code>.</p>
+</div>
+<div class="paragraph">
+<p>The same <code>bnd-maven-plugin</code> execution that produces the <a
href="#artifacts-osgi">OSGi manifest</a> also synthesizes a JPMS
<code>module-info</code> descriptor from the same metadata.
+This gives each module a proper, stable module name and its
<code>requires</code>, <code>exports</code>, <code>provides</code>, and
<code>uses</code> directives without a hand-written
<code>module-info.java</code>, which could not target Java 8 anyway.</p>
+</div>
+<div class="paragraph">
+<p>The module name defaults to the <code>Bundle-SymbolicName</code>, and the
<code>requires</code> directives are inferred from the imported packages.
+When that inference needs adjusting, use the following properties:</p>
+</div>
+<table class="tableblock frame-all grid-all stretch">
+<colgroup>
+<col style="width: 28.5714%;">
+<col style="width: 57.1428%;">
+<col style="width: 14.2858%;">
+</colgroup>
+<thead>
+<tr>
+<th class="tableblock halign-left valign-top">Property</th>
+<th class="tableblock halign-left valign-top">Purpose</th>
+<th class="tableblock halign-left valign-top">Default</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>bnd-module-name</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Override
the generated JPMS module name</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">the
<code>Bundle-SymbolicName</code></p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><code>bnd-extra-module-options</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Refine the
computed <code>requires</code> directives (see the <a
href="https://bnd.bndtools.org/chapters/330-jpms.html#advanced-options";>BND
JPMS options</a>); use only when <code>bnd-extra-package-options</code> cannot
express the change</p></td>
+<td class="tableblock halign-left valign-top"><p
class="tableblock"><em>(empty)</em></p></td>
+</tr>
+</tbody>
+</table>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>To keep incremental recompiles working, a <code>maven-clean-plugin</code>
execution deletes any stale
+<code>module-info.class</code> from the output directory before each
compilation.
+This works around a <code>javac</code> limitation and is not something you
need to configure.</p>
+</div>
+<div class="paragraph">
+<p>The same deletion, however, makes the classes folder look modified on every
invocation.
+Use <code>-Dbnd.skip</code> to suppress the BND processing when you do not
need to modify the descriptors.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+</div>
+<div class="sect2">
+<h3 id="artifacts-services"><a class="anchor"
href="#artifacts-services"></a>ServiceLoader descriptor</h3>
+<div class="paragraph">
+<p><em>Phase:</em> <code>process-classes</code>.</p>
+</div>
+<div class="paragraph">
+<p><code>java.util.ServiceLoader</code> requires a provider-registration file
under <code>META-INF/services/</code> and, on the module path, matching
<code>provides</code> and <code>uses</code> directives in
<code>module-info</code>.
+Rather than maintaining these by hand, Logging Parent lets BND generate them
from two annotations:</p>
+</div>
+<div class="dlist">
+<dl>
+<dt class="hdlist1"><code>aQute.bnd.annotation.spi.ServiceProvider</code></dt>
+<dd>
+<div class="paragraph">
+<p>Placed on a service <em>implementation</em>, it registers the class in the
appropriate <code>META-INF/services/<service></code> file and adds a
<code>provides <service> with <implementation></code> directive to
the JPMS descriptor.</p>
+</div>
+</dd>
+<dt class="hdlist1"><code>aQute.bnd.annotation.spi.ServiceConsumer</code></dt>
+<dd>
+<div class="paragraph">
+<p>Placed on a type that looks services up through <code>ServiceLoader</code>,
it adds the matching <code>uses <service></code> directive to the JPMS
descriptor.</p>
+</div>
+</dd>
+</dl>
+</div>
+<div class="paragraph">
+<p>Driving both the class-path (<code>META-INF/services/</code>) and
module-path (<code>module-info</code>) registrations from a single annotation
keeps the two representations from drifting apart.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="artifacts-sbom"><a class="anchor" href="#artifacts-sbom"></a>CycloneDX
SBOM</h3>
+<div class="paragraph">
+<p><em>Phase:</em> <code>package</code>.</p>
+</div>
+<div class="paragraph">
+<p>The <code>cyclonedx-maven-plugin</code> generates a
+<a href="https://cyclonedx.org/capabilities/vdr";>CycloneDX Software Bill of
Materials (SBOM)</a> for every module, describing its resolved dependencies.
+Each SBOM is attached as an XML artifact with the <code>cyclonedx</code>
classifier (<code><artifactId>-<version>-cyclonedx.xml</code>) and
carries a <code>vulnerability-assertion</code> external reference to the shared
Apache Logging Services VDR.
+See <a href="features.html#cyclonedx-sbom" class="xref
page">features.adoc#cyclonedx-sbom</a> for details.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="artifacts-asf"><a class="anchor" href="#artifacts-asf"></a>Embedded
LICENSE, NOTICE, and DEPENDENCIES</h3>
+<div class="paragraph">
+<p><em>Phase:</em> <code>generate-resources</code>.</p>
+</div>
+<div class="paragraph">
+<p>The <code>maven-remote-resources-plugin</code>, configured by the <a
href="https://maven.apache.org/pom/asf/";>ASF Parent POM</a> and its shared
resource bundle, contributes three files under the <code>META-INF/</code>
directory of every produced JAR:</p>
+</div>
+<div class="dlist">
+<dl>
+<dt class="hdlist1"><code>META-INF/LICENSE</code></dt>
+<dd>
+<p>the Apache License 2.0 text;</p>
+</dd>
+<dt class="hdlist1"><code>META-INF/NOTICE</code></dt>
+<dd>
+<p>the artifact’s attribution notices;</p>
+</dd>
+<dt class="hdlist1"><code>META-INF/DEPENDENCIES</code></dt>
+<dd>
+<p>a list of the module’s transitive dependencies, grouped by
organization and annotated with their licenses.</p>
+</dd>
+</dl>
+</div>
+<div class="paragraph">
+<p><code>META-INF/DEPENDENCIES</code> is always generated from the resolved
dependency tree.
+<code>META-INF/LICENSE</code> and <code>META-INF/NOTICE</code>, on the other
hand, are only <em>defaults</em>: a module’s own
<code>src/main/resources/META-INF/LICENSE</code> or
<code>META-INF/NOTICE</code> takes precedence, so a module that records
third-party attributions ships its curated files instead of the generated
ones.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="transformations"><a class="anchor"
href="#transformations"></a>Artifact transformations</h2>
+<div class="sectionbody">
+<div class="sect2">
+<h3 id="transformations-pom"><a class="anchor"
href="#transformations-pom"></a>POM flattening</h3>
+<div class="paragraph">
+<p><em>Phase:</em> <code>process-resources</code>.</p>
+</div>
+<div class="paragraph">
+<p>The POM you write is not the POM that gets published.
+Logging Parent uses <a
href="https://maven.apache.org/maven-ci-friendly.html";>CI-friendly
versioning</a>, so the project version is the <code>${revision}</code>
property, and a POM still holding an unresolved <code>${revision}</code> is not
consumable by Maven.
+The <code>flatten-maven-plugin</code> therefore rewrites the POM into a
<code>.flattened-pom.xml</code>, which is the file actually installed and
deployed.
+The rewrite runs in one of two modes:</p>
+</div>
+<div class="dlist">
+<dl>
+<dt class="hdlist1">Default (<code>resolveCiFriendliesOnly</code>)</dt>
+<dd>
+<div class="paragraph">
+<p>Only the CI-friendly properties (<code>${revision}</code> and friends) are
resolved; the rest of the POM, including its <code>parent</code>, is preserved
as-is.</p>
+</div>
+</dd>
+<dt class="hdlist1">BOM (<code>bom</code>)</dt>
+<dd>
+<div class="paragraph">
+<p><em>Activated by <code>.logging-parent-bom-activator</code>.</em>
+The POM is reduced to a self-contained Bill of Materials: besides resolving
the version, the <code>parent</code>, <code>build</code>,
<code>properties</code>, and <code>profiles</code> sections are removed,
leaving only the managed dependencies.
+This keeps consumers of the BOM free of unrelated build configuration.</p>
+</div>
+<div class="paragraph">
+<p>A BOM must therefore <strong>not</strong> reference a property defined
solely in an ancestor POM: <code>bom</code>-mode interpolation resolves
variables from the module’s own POM only, so an inherited property would
be left unresolved after flattening.</p>
+</div>
+</dd>
+</dl>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="optional-extensions"><a class="anchor"
href="#optional-extensions"></a>Optional lifecycle extensions</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The following profiles are not activated automatically; you enable them on
the command line to add behavior to an otherwise normal build.</p>
+</div>
+<div class="dlist">
+<dl>
+<dt class="hdlist1"><code>-Prelease</code></dt>
+<dd>
+<p>Generates the additional artifacts a release requires: it attaches the
<code>-sources</code> JAR and enforces that neither the project version nor any
of its dependencies is a SNAPSHOT.</p>
+<div class="paragraph">
+<p>Both conditions must hold: the project version itself must be a release
version, and <strong>every</strong> dependency must be a non-SNAPSHOT
version.</p>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+Apache Logging Service projects do <strong>not</strong> use the ASF Parent
POM’s <code>apache-release</code> profile; this <code>release</code>
profile, together with the <code>deploy</code> or <code>distribution</code>
commands, replace it.
+</td>
+</tr>
+</table>
+</div>
+</dd>
+<dt class="hdlist1"><code>-Pcoverage</code></dt>
+<dd>
+<p>Runs the <code>jacoco-maven-plugin</code> to collect test coverage during
the build and write an HTML report under <code>target/site/jacoco</code>.</p>
+</dd>
+<dt class="hdlist1"><code>-Dapache.snapshots</code></dt>
+<dd>
+<p>Activates the ASF Parent POM’s <code>use-apache-snapshots</code>
profile, adding the <a href="https://repository.apache.org/snapshots";>Apache
snapshots repository</a>.
+It lets you build only some modules of a project and resolve the rest from the
regularly published SNAPSHOT artifacts, instead of building every upstream
module locally.</p>
+</dd>
+</dl>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="commands"><a class="anchor" href="#commands"></a>Additional
commands</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>A few profiles are not lifecycle extensions but <em>commands</em>: each
carries a <code>defaultGoal</code>, so enabling the profile without naming a
phase runs a single task and nothing else.
+They are normally invoked by the reusable deployment workflows, but can also
be run by hand.</p>
+</div>
+<div class="dlist">
+<dl>
+<dt class="hdlist1"><code>./mvnw -Pchangelog-release</code></dt>
+<dd>
+<p>Moves the pending changelog entries from
<code>src/changelog/.<major>.x.x/</code> into the released
version’s directory and regenerates the release notes.</p>
+</dd>
+<dt class="hdlist1"><code>./mvnw -Pdistribution</code></dt>
+<dd>
+<p>Builds the source (<code>src.zip</code>) and binary (<code>bin.zip</code>)
distribution archives from the Git-tracked files.
+Requires the <code>attachmentFilepathPattern</code> and
<code>attachmentCount</code> properties and a prior <code>package</code>.</p>
+</dd>
+<dt class="hdlist1"><code>./mvnw -Pdeploy</code></dt>
+<dd>
+<p>Signs the artifacts and deploys them to the Apache Nexus staging repository
via the <code>nexus-staging-maven-plugin</code> (skipping tests, SpotBugs, and
Spotless).</p>
+</dd>
+</dl>
+</div>
+</div>
+</div>
+</article>
+ </div>
+</main>
+</div>
+<footer class="footer">
+ <p>
+ Copyright © 1999-2026 <a href="https://www.apache.org/";>The Apache
Software Foundation</a>.
+ Licensed under the <a
href="https://www.apache.org/licenses/LICENSE-2.0";>Apache Software License,
Version 2.0</a>.
+ Please read our <a
href="https://privacy.apache.org/policies/privacy-policy-public.html";>privacy
policy</a>.
+ </p>
+ <p>
+ Apache, Log4j, and the Apache feather logo are trademarks or registered
trademarks of The Apache Software Foundation.
+ Oracle and Java are registered trademarks of Oracle and/or its affiliates.
+ Other names may be trademarks of their respective owners.
+ </p>
+</footer>
+<script id="site-script" src="./_/js/site.js" data-ui-root-path="./_"></script>
+<script async src="./_/js/vendor/highlight.js"></script>
+<!-- `@asciidoctor/tabs` extension scripts -->
+<script async src="./_/js/vendor/tabs.js"></script>
+ </body>
+</html>
diff --git a/features.html b/features.html
index 8a76f28..90f607b 100644
--- a/features.html
+++ b/features.html
@@ -73,6 +73,18 @@
<li class="nav-item" data-depth="1">
<a class="nav-link" href="release-notes.html">Release notes</a>
</li>
+</ul>
+ </li>
+ <li class="nav-item" data-depth="0">
+ <button class="nav-item-toggle"></button>
+ <span class="nav-text">Build</span>
+<ul class="nav-list">
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="build-lifecycle.html">Build lifecycle</a>
+ </li>
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="troubleshooting.html">Troubleshooting</a>
+ </li>
</ul>
</li>
<li class="nav-item" data-depth="0">
diff --git a/index.html b/index.html
index 6711c91..598e826 100644
--- a/index.html
+++ b/index.html
@@ -73,6 +73,18 @@
<li class="nav-item" data-depth="1">
<a class="nav-link" href="release-notes.html">Release notes</a>
</li>
+</ul>
+ </li>
+ <li class="nav-item" data-depth="0">
+ <button class="nav-item-toggle"></button>
+ <span class="nav-text">Build</span>
+<ul class="nav-list">
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="build-lifecycle.html">Build lifecycle</a>
+ </li>
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="troubleshooting.html">Troubleshooting</a>
+ </li>
</ul>
</li>
<li class="nav-item" data-depth="0">
diff --git a/release-instructions-project.html
b/release-instructions-project.html
index 82d65dd..1b24e5b 100644
--- a/release-instructions-project.html
+++ b/release-instructions-project.html
@@ -73,6 +73,18 @@
<li class="nav-item" data-depth="1">
<a class="nav-link" href="release-notes.html">Release notes</a>
</li>
+</ul>
+ </li>
+ <li class="nav-item" data-depth="0">
+ <button class="nav-item-toggle"></button>
+ <span class="nav-text">Build</span>
+<ul class="nav-list">
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="build-lifecycle.html">Build lifecycle</a>
+ </li>
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="troubleshooting.html">Troubleshooting</a>
+ </li>
</ul>
</li>
<li class="nav-item" data-depth="0">
diff --git a/release-instructions-xml-schema.html
b/release-instructions-xml-schema.html
index 15a60fc..9935201 100644
--- a/release-instructions-xml-schema.html
+++ b/release-instructions-xml-schema.html
@@ -73,6 +73,18 @@
<li class="nav-item" data-depth="1">
<a class="nav-link" href="release-notes.html">Release notes</a>
</li>
+</ul>
+ </li>
+ <li class="nav-item" data-depth="0">
+ <button class="nav-item-toggle"></button>
+ <span class="nav-text">Build</span>
+<ul class="nav-list">
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="build-lifecycle.html">Build lifecycle</a>
+ </li>
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="troubleshooting.html">Troubleshooting</a>
+ </li>
</ul>
</li>
<li class="nav-item" data-depth="0">
diff --git a/release-notes.html b/release-notes.html
index 9593122..af155bf 100644
--- a/release-notes.html
+++ b/release-notes.html
@@ -73,6 +73,18 @@
<li class="nav-item is-current-page" data-depth="1">
<a class="nav-link" href="release-notes.html">Release notes</a>
</li>
+</ul>
+ </li>
+ <li class="nav-item" data-depth="0">
+ <button class="nav-item-toggle"></button>
+ <span class="nav-text">Build</span>
+<ul class="nav-list">
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="build-lifecycle.html">Build lifecycle</a>
+ </li>
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="troubleshooting.html">Troubleshooting</a>
+ </li>
</ul>
</li>
<li class="nav-item" data-depth="0">
diff --git a/release-review-instructions.html b/release-review-instructions.html
index 4fe49b9..c7b4d3c 100644
--- a/release-review-instructions.html
+++ b/release-review-instructions.html
@@ -73,6 +73,18 @@
<li class="nav-item" data-depth="1">
<a class="nav-link" href="release-notes.html">Release notes</a>
</li>
+</ul>
+ </li>
+ <li class="nav-item" data-depth="0">
+ <button class="nav-item-toggle"></button>
+ <span class="nav-text">Build</span>
+<ul class="nav-list">
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="build-lifecycle.html">Build lifecycle</a>
+ </li>
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="troubleshooting.html">Troubleshooting</a>
+ </li>
</ul>
</li>
<li class="nav-item" data-depth="0">
diff --git a/sitemap.xml b/sitemap.xml
index 931474e..3a53d17 100644
--- a/sitemap.xml
+++ b/sitemap.xml
@@ -1,35 +1,43 @@
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9";>
<url>
+<loc>https://logging.apache.org/logging-parent/build-lifecycle.html</loc>
+<lastmod>2026-07-24T16:08:49.438Z</lastmod>
+</url>
+<url>
<loc>https://logging.apache.org/logging-parent/features.html</loc>
-<lastmod>2026-02-17T14:23:56.496Z</lastmod>
+<lastmod>2026-07-24T16:08:49.438Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/logging-parent/index.html</loc>
-<lastmod>2026-02-17T14:23:56.496Z</lastmod>
+<lastmod>2026-07-24T16:08:49.438Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/logging-parent/release-instructions-project.html</loc>
-<lastmod>2026-02-17T14:23:56.496Z</lastmod>
+<lastmod>2026-07-24T16:08:49.438Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/logging-parent/release-instructions-xml-schema.html</loc>
-<lastmod>2026-02-17T14:23:56.496Z</lastmod>
+<lastmod>2026-07-24T16:08:49.438Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/logging-parent/release-notes.html</loc>
-<lastmod>2026-02-17T14:23:56.496Z</lastmod>
+<lastmod>2026-07-24T16:08:49.438Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/logging-parent/release-review-instructions.html</loc>
-<lastmod>2026-02-17T14:23:56.496Z</lastmod>
+<lastmod>2026-07-24T16:08:49.438Z</lastmod>
+</url>
+<url>
+<loc>https://logging.apache.org/logging-parent/troubleshooting.html</loc>
+<lastmod>2026-07-24T16:08:49.438Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/logging-parent/usage.html</loc>
-<lastmod>2026-02-17T14:23:56.496Z</lastmod>
+<lastmod>2026-07-24T16:08:49.438Z</lastmod>
</url>
<url>
<loc>https://logging.apache.org/logging-parent/workflows.html</loc>
-<lastmod>2026-02-17T14:23:56.496Z</lastmod>
+<lastmod>2026-07-24T16:08:49.438Z</lastmod>
</url>
</urlset>
diff --git a/troubleshooting.html b/troubleshooting.html
new file mode 100644
index 0000000..6fc4638
--- /dev/null
+++ b/troubleshooting.html
@@ -0,0 +1,394 @@
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <meta charset="utf-8">
+ <meta name="viewport" content="width=device-width,initial-scale=1">
+ <title>Troubleshooting :: Apache Logging Parent</title>
+ <link rel="canonical"
href="https://logging.apache.org/logging-parent/troubleshooting.html";>
+ <meta name="generator" content="Antora 3.2.0-alpha.8">
+<link rel="stylesheet" href="./_/css/site.css">
+<link rel="icon" href="./_/../_images/favicon.ico" type="image/x-icon">
+<!-- `@asciidoctor/tabs` extension styles -->
+<link rel="stylesheet" href="./_/css/vendor/tabs.css">
+<style>
+ /* Swap colors of `IMPORTANT` and `WARNING` blocks */
+ .doc .admonitionblock.important .icon { background-color: #f70; }
+ .doc .admonitionblock.warning .icon { background-color: #e40046; }
+ /* Default `h4`, `h5`, and `h6` are smaller than the normal text, fix header
font sizing: */
+ .doc h1 { font-size: 1.9rem; }
+ .doc h2 { font-size: 1.7rem; }
+ .doc h3 { font-size: 1.5rem; font-weight: 400; }
+ .doc h4 { font-size: 1.3rem; font-weight: 500; }
+ .doc h5 { font-size: 1.1rem; font-weight: 500; text-decoration: underline; }
+ .doc h6 { font-size: 0.9rem; font-weight: 500; text-decoration: underline; }
+ /* Default `code`, `pre`, and `.colist` (source code annotations) fonts are
too big, adjust them: */
+ .doc .colist>table code, .doc p code, .doc thead code { font-size: 0.8em; }
+ .doc pre { font-size: 0.7rem; }
+ .doc .colist { font-size: 0.75rem; }
+ /* Make links more visible: */
+ .doc a { text-decoration: underline; }
+ .doc a code { text-decoration: underline; color: #1565c0; }
+ /* Tab header fonts aren't rendered good, adjusting the font weight: */
+ .tablist > ul li { font-weight: 500; }
+ /* `page-toclevels` greater than 4 are not supported by Antora UI, patching
it: */
+ .toc .toc-menu li[data-level="4"] a {
+ padding-left: 2.75rem;
+ }
+ /* Replace the default highlight.js color for strings from red
(unnecessarily signaling something negative) to green: */
+ .hljs-string {
+ color: #0f8532;
+ }
+</style>
+ </head>
+ <body class="article">
+<header class="header">
+ <nav class="navbar">
+ <div class="navbar-brand">
+ <span class="navbar-item title">Apache Logging Parent</span>
+ </div>
+ <div id="topbar-nav" class="navbar-menu">
+ <div class="navbar-end">
+ <a class="navbar-item" href="https://logging.apache.org";>a subproject
of <strong>Apache Logging Services</strong></a>
+ </div>
+ </div>
+ </nav>
+</header>
+<div class="body">
+<div class="nav-container" data-component="ROOT" data-version="">
+ <aside class="nav">
+ <div class="panels">
+<div class="nav-panel-menu is-active" data-panel="menu">
+ <nav class="nav-menu">
+ <button class="nav-menu-toggle" aria-label="Toggle expand/collapse all"
style="display: none"></button>
+ <h3 class="title"><a href="index.html">Home</a></h3>
+<ul class="nav-list">
+ <li class="nav-item" data-depth="0">
+<ul class="nav-list">
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="features.html">Features</a>
+ </li>
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="usage.html">Usage</a>
+ </li>
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="release-notes.html">Release notes</a>
+ </li>
+</ul>
+ </li>
+ <li class="nav-item" data-depth="0">
+ <button class="nav-item-toggle"></button>
+ <span class="nav-text">Build</span>
+<ul class="nav-list">
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="build-lifecycle.html">Build lifecycle</a>
+ </li>
+ <li class="nav-item is-current-page" data-depth="1">
+ <a class="nav-link" href="troubleshooting.html">Troubleshooting</a>
+ </li>
+</ul>
+ </li>
+ <li class="nav-item" data-depth="0">
+ <button class="nav-item-toggle"></button>
+ <span class="nav-text">Release support</span>
+<ul class="nav-list">
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="release-review-instructions.html">Project
release review instructions</a>
+ </li>
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="release-instructions-project.html">Project
release instructions</a>
+ </li>
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="release-instructions-xml-schema.html">XML schema
release instructions</a>
+ </li>
+</ul>
+ </li>
+</ul>
+ </nav>
+</div>
+ </div>
+ </aside>
+</div>
+<main class="article">
+<div class="toolbar" role="navigation">
+<button class="nav-toggle"></button>
+ <a href="index.html" class="home-link"></a>
+<nav class="breadcrumbs" aria-label="breadcrumbs">
+ <ul>
+ <li><a href="index.html">Home</a></li>
+ <li>Build</li>
+ <li><a href="troubleshooting.html">Troubleshooting</a></li>
+ </ul>
+</nav>
+<div class="edit-this-page"><a
href="https://github.com/apache/logging-parent/edit/main/src/site/antora/modules/ROOT/pages/troubleshooting.adoc";>Edit
this Page</a></div>
+</div>
+ <div class="content">
+<aside class="toc sidebar" data-title="Contents" data-levels="2">
+ <div class="toc-menu"></div>
+</aside>
+<article class="doc">
+<h1 class="page">Troubleshooting</h1>
+<div id="preamble">
+<div class="sectionbody">
+<div class="paragraph">
+<p>This page collects debugging recipes for the build checks that are not
self-explanatory.</p>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+The version numbers <code>x.y.z</code> and <code>a.b.c</code> used on this
page are placeholders for the project version and a package version, with
increments written as <code>x.y+1.0</code> or <code>a.b.c+1</code>.
+Real build output contains concrete versions instead.
+</td>
+</tr>
+</table>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="bnd-baseline"><a class="anchor" href="#bnd-baseline"></a>API
compatibility (BND baseline)</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The <a href="build-lifecycle.html#check-api-compatibility" class="xref
page">API compatibility check</a> (<code>bnd-baseline-maven-plugin</code>)
fails a build when the public API of a module changed in a way that is not
reflected in its version numbers.
+When it trips, <code>./mvnw verify</code> prints a report (also written to
<code>target/baseline/<artifactId>-<version>.txt</code>) similar
to:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-none
hljs">===============================================================
+ Name Type Delta New Old
Suggest
+ org.apache.logging.log4j.api BUNDLE MAJOR x.y+1.0.SNAPSHOT x.y.z
-
+===============================================================
+ Name Type Delta New Old
Suggest If Prov.
+* org.apache.logging.log4j PACKAGE MINOR a.b.c a.b.c
a.b+1.0 -
+ MINOR PACKAGE org.apache.logging.log4j
+ MINOR CLASS org.apache.logging.log4j.MarkerManager
+ ADDED METHOD triggerBaselineError()
+ ADDED ACCESS static
+ ADDED RETURN int
+ org.apache.logging.log4j.message PACKAGE UNCHANGED d.e.f d.e.f ok
-
+ ...</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Read it as follows:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>The rows marked with <code>*</code> are the ones you must fix.</p>
+</li>
+<li>
+<p><code>Delta</code> is the kind of change BND detected in that package:
<code>MICRO</code>, <code>MINOR</code>, or <code>MAJOR</code>.</p>
+</li>
+<li>
+<p><code>Old</code> is the version of the package in the last release,
<code>New</code> is the version you currently declare.</p>
+</li>
+<li>
+<p><code>Suggest</code> is the <strong>minimal</strong> version that would
satisfy the detected change.</p>
+<div class="admonitionblock important">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-important" title="Important"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>The <code>Suggest</code> value is only BND’s <em>minimal</em>
acceptable version; we do not always adopt it verbatim.
+For a <code>MICRO</code> change we follow the suggestion, but for a
<code>MINOR</code> change we align the package version with the project version
instead.
+See <a href="#bnd-baseline-why">Why these rules?</a> for the rationale.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+</li>
+<li>
+<p>The indented tree below a package explains <em>why</em> that delta was
computed (here, a <code>static</code> method
<code>triggerBaselineError()</code> was <code>ADDED</code>).</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Package versions are declared with the <code>@Version</code> annotation of
the package’s <code>package-info.java</code>:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-java hljs"
data-lang="java">@Version("a.b.c")
+package org.apache.logging.log4j;</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>How you resolve the failure depends on the <code>Delta</code>.</p>
+</div>
+<div class="sect2">
+<h3 id="bnd-baseline-micro"><a class="anchor"
href="#bnd-baseline-micro"></a><code>MICRO</code></h3>
+<div class="paragraph">
+<p>A change that is both binary- and source-compatible but that BND still
detects, most commonly an annotation added to or removed from an API member and
retained in its bytecode.</p>
+</div>
+<div class="paragraph">
+<p>Bump the <strong>patch</strong> component of the package version to the
value in the <code>Suggest</code> column, <strong>not</strong> to the upcoming
project version, by editing its <code>package-info.java</code>:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-java hljs"
data-lang="java">@Version("a.b.c+1")
+package org.apache.logging.log4j;</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Here we keep the suggested <code>a.b.c+1</code>, regardless of the upcoming
project version; see <a href="#bnd-baseline-why">Why these rules?</a>.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="bnd-baseline-minor"><a class="anchor"
href="#bnd-baseline-minor"></a><code>MINOR</code></h3>
+<div class="paragraph">
+<p>A backward-compatible addition to the public API: a new method, class,
field, or constant.
+In the report above, adding the <code>triggerBaselineError()</code> method
produced a <code>MINOR</code> delta on
<code>org.apache.logging.log4j</code>.</p>
+</div>
+<div class="paragraph">
+<p>Resolve it in three steps:</p>
+</div>
+<div class="olist arabic">
+<ol class="arabic">
+<li>
+<p><strong>Make the project version a minor upgrade over the last
release.</strong>
+Adding API requires a new minor release, so the project version must reflect
it.
+If the <code><revision></code> property is only a patch upgrade (for
example <code>x.y.1-SNAPSHOT</code> after the <code>x.y.0</code> release),
raise it to the next minor version (<code>x.y+1.0-SNAPSHOT</code>).</p>
+</li>
+<li>
+<p><strong>Record the change in the changelog.</strong>
+Add an entry of type <code>added</code> (or <code>changed</code> /
<code>deprecated</code>, as appropriate) to the pending changelog directory
<code>src/changelog/.<major>.x.x/</code>, so the addition appears in the
release notes.</p>
+</li>
+<li>
+<p><strong>Bump the package version.</strong>
+Set the <code>@Version</code> in the package’s
<code>package-info.java</code> to the upcoming project version,
<strong>not</strong> to the minimal value in the <code>Suggest</code>
column:</p>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-java hljs"
data-lang="java">@Version("x.y+1.0")
+package org.apache.logging.log4j;</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Using the project version <code>x.y+1.0</code> rather than the suggested
<code>a.b+1.0</code> is deliberate; see <a href="#bnd-baseline-why">Why these
rules?</a>.</p>
+</div>
+</li>
+</ol>
+</div>
+</div>
+<div class="sect2">
+<h3 id="bnd-baseline-major"><a class="anchor"
href="#bnd-baseline-major"></a><code>MAJOR</code></h3>
+<div class="paragraph">
+<p>A breaking change: a public member was removed, renamed, or changed in an
incompatible way.
+On a stable branch (for example Log4j <code>2.x</code>) this is
<strong>not</strong> accepted, and bumping the package major version is not an
option.</p>
+</div>
+<div class="paragraph">
+<p>Instead of changing the version, rework the change so that it stays
backward-compatible, for example by deprecating a member instead of removing
it, or by adding an overload instead of altering an existing signature.</p>
+</div>
+<div class="paragraph">
+<p>If you are convinced the report is a false positive (for example, the
member you removed was documented as private), ask the development team before
overriding the check.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="bnd-baseline-why"><a class="anchor" href="#bnd-baseline-why"></a>Why
these rules?</h3>
+<div class="paragraph">
+<p>These conventions make a package’s <code>@Version</code> tell you, at
a glance, when its public API last changed.</p>
+</div>
+<div class="paragraph">
+<p>Because a <code>MINOR</code> change sets the package version to the project
version, while a <code>MICRO</code> change only increments the patch component,
a package version such as <code>a.b.c</code> reads as:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>its public API last changed in release <code>a.b.0</code>, and</p>
+</li>
+<li>
+<p><code>c</code> smaller, API-compatible revisions have been published
since.</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Had we used BND’s minimal <code>Suggest</code> value instead, the
minor component would not line up with any release, and the version would carry
no such meaning.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="require-upper-bound-deps"><a class="anchor"
href="#require-upper-bound-deps"></a>Order-independent dependency
resolution</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>The <a href="build-lifecycle.html#check-dependency-convergence" class="xref
page">Order-independent dependency resolution check</a> (the
<code>maven-enforcer-plugin</code> <code>requireUpperBoundDeps</code> rule)
fails when the version Maven resolves for a dependency is lower than a version
required elsewhere in the graph.</p>
+</div>
+<div class="paragraph">
+<p>A failure looks like this:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-none hljs">Rule 0:
...RequireUpperBoundDeps failed with message:
+Failed while enforcing RequireUpperBoundDeps. The error(s) are [
+Require upper bound dependencies error for commons-codec:commons-codec:1.10.
Paths to dependency are:
++-test:upperbound-test:1.0
+ +-commons-codec:commons-codec:1.10
+and
++-test:upperbound-test:1.0
+ +-org.apache.httpcomponents:httpclient:4.5.13
+ +-commons-codec:commons-codec:1.11
+]</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Read it as follows:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>The header names the <strong>resolved</strong> version that is too low
(<code>commons-codec:1.10</code>).</p>
+</li>
+<li>
+<p>Each <code>Paths to dependency</code> block is one route through the tree.
+The first route shows how the low version was selected (here
<code>commons-codec</code> is declared directly); the others show who requires
a higher version (<code>httpclient:4.5.13</code> needs <code>1.11</code>).</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>To fix it, find where the too-low version is defined, usually in the
project’s parent POM, where all dependency versions are managed.</p>
+</div>
+<div class="dlist">
+<dl>
+<dt class="hdlist1">If the parent POM does <strong>not</strong> pin
<code>commons-codec</code></dt>
+<dd>
+<p>Add it to the parent’s <code><dependencyManagement></code> at a
version at least as high as the highest one required (<code>1.11</code>
here).</p>
+</dd>
+<dt class="hdlist1">If the parent POM already pins
<code>commons-codec</code></dt>
+<dd>
+<p>The pin is what forced the lower version, so it is the cause of the failure.
+Bump it to at least the required minimum (<code>1.11</code>).</p>
+<div class="paragraph">
+<p>It is also worth trying to <strong>remove</strong> the pin altogether: the
direct dependencies that once needed it may have since upgraded to mutually
compatible versions, making the pin unnecessary.</p>
+</div>
+</dd>
+</dl>
+</div>
+</div>
+</div>
+</article>
+ </div>
+</main>
+</div>
+<footer class="footer">
+ <p>
+ Copyright © 1999-2026 <a href="https://www.apache.org/";>The Apache
Software Foundation</a>.
+ Licensed under the <a
href="https://www.apache.org/licenses/LICENSE-2.0";>Apache Software License,
Version 2.0</a>.
+ Please read our <a
href="https://privacy.apache.org/policies/privacy-policy-public.html";>privacy
policy</a>.
+ </p>
+ <p>
+ Apache, Log4j, and the Apache feather logo are trademarks or registered
trademarks of The Apache Software Foundation.
+ Oracle and Java are registered trademarks of Oracle and/or its affiliates.
+ Other names may be trademarks of their respective owners.
+ </p>
+</footer>
+<script id="site-script" src="./_/js/site.js" data-ui-root-path="./_"></script>
+<script async src="./_/js/vendor/highlight.js"></script>
+<!-- `@asciidoctor/tabs` extension scripts -->
+<script async src="./_/js/vendor/tabs.js"></script>
+ </body>
+</html>
diff --git a/usage.html b/usage.html
index c91b9a5..206dee5 100644
--- a/usage.html
+++ b/usage.html
@@ -73,6 +73,18 @@
<li class="nav-item" data-depth="1">
<a class="nav-link" href="release-notes.html">Release notes</a>
</li>
+</ul>
+ </li>
+ <li class="nav-item" data-depth="0">
+ <button class="nav-item-toggle"></button>
+ <span class="nav-text">Build</span>
+<ul class="nav-list">
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="build-lifecycle.html">Build lifecycle</a>
+ </li>
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="troubleshooting.html">Troubleshooting</a>
+ </li>
</ul>
</li>
<li class="nav-item" data-depth="0">
diff --git a/workflows.html b/workflows.html
index beef241..2b30e22 100644
--- a/workflows.html
+++ b/workflows.html
@@ -73,6 +73,18 @@
<li class="nav-item" data-depth="1">
<a class="nav-link" href="release-notes.html">Release notes</a>
</li>
+</ul>
+ </li>
+ <li class="nav-item" data-depth="0">
+ <button class="nav-item-toggle"></button>
+ <span class="nav-text">Build</span>
+<ul class="nav-list">
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="build-lifecycle.html">Build lifecycle</a>
+ </li>
+ <li class="nav-item" data-depth="1">
+ <a class="nav-link" href="troubleshooting.html">Troubleshooting</a>
+ </li>
</ul>
</li>
<li class="nav-item" data-depth="0">
