This is an automated email from the ASF dual-hosted git repository.
jamesbognar pushed a commit to branch docs
in repository https://gitbox.apache.org/repos/asf/juneau.git
The following commit(s) were added to refs/heads/docs by this push:
new 3646155bd3 build: add juneau-bom and curated dependency bundles
(jetty/tomcat/springboot)
3646155bd3 is described below
commit 3646155bd315fe2948027522418b905f8253e535
Author: James Bognar <[email protected]>
AuthorDate: Thu Jun 18 15:03:22 2026 -0400
build: add juneau-bom and curated dependency bundles
(jetty/tomcat/springboot)
---
pages/release-notes/10.0.0.md | 32 +++++++++
pages/topics/17.01.DependencyManagement.md | 106 +++++++++++++++++++++++++++++
pages/topics/18.01.StarterProjects.md | 5 ++
sidebars.ts | 12 ++++
4 files changed, 155 insertions(+)
diff --git a/pages/release-notes/10.0.0.md b/pages/release-notes/10.0.0.md
index f9aaa597ea..5920a9aea6 100644
--- a/pages/release-notes/10.0.0.md
+++ b/pages/release-notes/10.0.0.md
@@ -155,6 +155,38 @@ JettySettings jettySettings() {
See the new [Graceful Shutdown & Readiness
Gating](/docs/topics/GracefulShutdown) topic page for details, including the
Jetty/Tomcat parity table and Kubernetes deployment guidance.
+### Build & packaging (BOM + curated bundles)
+
+#### Published BOM + curated dependency bundles
+
+Juneau now publishes a **Bill of Materials** and a small set of **curated
dependency bundles** so consumers can depend on a coherent, version-aligned
slice of the framework without hand-maintaining `<version>` tags — while
keeping Juneau's **explicit-over-magic** configuration model (no Spring-style
classpath auto-configuration).
+
+- **`org.apache.juneau:juneau-bom`** (packaging `pom`) — import it
(`scope=import`, `type=pom`) and drop explicit versions from your Juneau
dependencies. Enumerates the consumer-facing Juneau modules plus the small set
of starter-relevant third-party versions the bundles need (`micrometer-core`,
`opentelemetry-api`, `jakarta.servlet-api`, `jakarta.validation-api`). It is
**not** a whole-world third-party BOM, so it won't collide with a third-party
BOM you import yourself.
+- **Three deployment-shape bundles** (packaging `pom`) — depend on one and
transitively pull a coherent module set plus `juneau-rest-client`:
+ - `juneau-microservice-jetty-bundle`
+ - `juneau-microservice-tomcat-bundle`
+ - `juneau-springboot-bundle`
+
+```xml
+<dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.juneau</groupId>
+ <artifactId>juneau-bom</artifactId>
+ <version>10.0.0</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+</dependencyManagement>
+```
+
+The bundles are **dependency aggregators only** — they register no
configurations and perform no classpath auto-discovery. Configuration
registration stays explicit via
`Microservice.Builder.configurations(Class<?>...)`. This is a deliberate design
choice: per the maintainer, *"I actually see auto-configuration as a weakness
in Spring Boot that leads to applications with long startup times and
impossible-to-understand architectures."* These bundles are also distinct from
the external clo [...]
+
+A reactor-consistency guard (`scripts/check-bom-completeness.py`, wired into
the push gate) fails the build if a published module is missing from the BOM,
so the enumeration can't silently drift. The binary distribution now also
bundles `juneau-microservice-tomcat` (previously omitted).
+
+See the new [Dependency Management (BOM &
Bundles)](/docs/topics/DependencyManagement) topic page for usage and the full
explicit-over-magic rationale.
+
### juneau-petstore (new module family)
Three new modules under a top-level `juneau-petstore/` aggregator together
form the canonical Juneau petstore showcase application. The legacy
`juneau-examples-rest{,-jetty,-springboot,-jetty-ftest}` family of modules has
been retired in this release in favor of the petstore family — see the
**Breaking Changes** section below.
diff --git a/pages/topics/17.01.DependencyManagement.md
b/pages/topics/17.01.DependencyManagement.md
new file mode 100644
index 0000000000..552b8c384c
--- /dev/null
+++ b/pages/topics/17.01.DependencyManagement.md
@@ -0,0 +1,106 @@
+---
+title: "Dependency Management (BOM & Bundles)"
+slug: DependencyManagement
+---
+
+Apache Juneau ships two packaging aids that make it easy to depend on a
coherent, version-aligned slice
+of the framework without hand-maintaining a long list of `<version>` tags:
+
+- A **Bill of Materials (BOM)** — `org.apache.juneau:juneau-bom` — for version
alignment.
+- A small set of curated **dependency bundles** — one per deployment shape —
that transitively pull a
+ coherent module set.
+
+Both are deliberately **dependency-only** aids. They register nothing and
discover nothing at runtime
+(see [Explicit over magic](#explicit-over-magic-no-auto-configuration) below).
+
+## The BOM
+
+Import `juneau-bom` (scope `import`, type `pom`) in your
`<dependencyManagement>` and then drop the
+explicit versions from every Juneau dependency — the BOM supplies them:
+
+```xml
+<dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.juneau</groupId>
+ <artifactId>juneau-bom</artifactId>
+ <version>10.0.0</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+</dependencyManagement>
+
+<dependencies>
+ <!-- No <version> needed - the BOM aligns it. -->
+ <dependency>
+ <groupId>org.apache.juneau</groupId>
+ <artifactId>juneau-marshall</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.juneau</groupId>
+ <artifactId>juneau-rest-server</artifactId>
+ </dependency>
+</dependencies>
+```
+
+The BOM enumerates the **consumer-facing** Juneau modules (juneau-core
marshalling/config, juneau-rest,
+juneau-microservice, juneau-bean, juneau-sc). It excludes
internal/test/aggregate artifacts
+(`juneau-test-utils`, `juneau-shaded/*`, `juneau-examples`, `juneau-petstore`,
`juneau-distrib`).
+
+Beyond Juneau's own modules, the BOM also pins the small set of
starter-relevant third-party versions the
+bundles need to stay coherent — `micrometer-core`, `opentelemetry-api`,
`jakarta.servlet-api`, and
+`jakarta.validation-api`. It is **not** a whole-world third-party BOM (unlike
Spring Boot's), so it won't
+collide with a third-party BOM you import yourself.
+
+## The bundles
+
+Each bundle is a `pom`-packaged aggregator for one deployment shape. Depend on
a single bundle and you
+transitively pull a coherent module set plus the REST client:
+
+| Bundle | Deployment shape | Pulls (transitively) |
+| --- | --- | --- |
+| `juneau-microservice-jetty-bundle` | Embedded-Jetty microservice |
`juneau-microservice-jetty` → `juneau-microservice` + `juneau-rest-server`,
plus `juneau-rest-client` |
+| `juneau-microservice-tomcat-bundle` | Embedded-Tomcat microservice |
`juneau-microservice-tomcat` → `juneau-microservice` + `juneau-rest-server`,
plus `juneau-rest-client` |
+| `juneau-springboot-bundle` | Spring Boot bridge |
`juneau-rest-server-springboot` (brings `juneau-rest-server` +
`spring-boot-starter-web`), plus `juneau-rest-client` |
+
+```xml
+<dependency>
+ <groupId>org.apache.juneau</groupId>
+ <artifactId>juneau-microservice-jetty-bundle</artifactId>
+ <version>10.0.0</version>
+ <type>pom</type>
+</dependency>
+```
+
+The bundles internally import `juneau-bom`, so the modules they pull are
already version-aligned.
+
+> **Bundle vs. starter.** These `*-bundle` POMs are *dependency aggregators* —
add one dependency, get a
+> coherent module set. They are not to be confused with the external
clone-and-go
+> [starter project repos](/docs/topics/StarterProjects)
(`juneau-microservice-*-starter`), which are full
+> runnable project templates.
+
+## Explicit over magic (no auto-configuration)
+
+A bundle gives you the *classpath* for a deployment shape. It does **not**
wire anything up for you. Juneau
+keeps configuration registration **explicit** — you register your
configuration classes yourself through
+`Microservice.Builder.configurations(Class<?>...)`. There is no
`ServiceLoader` / `META-INF/services`
+scan and no `@ConditionalOnClass`-style classpath auto-discovery that decides
what to activate based on
+what happens to be on the classpath.
+
+This is a deliberate design choice, not a missing feature. In the maintainer's
words:
+
+> *"No, we want an explicit classpath-driven solution. I actually see
auto-configuration as a weakness in
+> Spring Boot that leads to applications with long startup times and
impossible-to-understand
+> architectures. We should make this distinction clear in our docs."*
+
+The two costs called out there are exactly what the explicit model avoids:
+
+- **Startup time.** No classpath scanning for conditional configuration to
evaluate at boot. What you
+ register is what runs.
+- **Comprehensibility.** The set of active configurations is the literal list
you passed to
+ `configurations(...)` — readable in one place, with no implicit behavior
toggled on by a transitive
+ dependency you didn't realize was present.
+
+So the division of labor is clean: the **BOM** aligns versions, the
**bundles** assemble a coherent
+classpath, and **you** stay in explicit control of what gets wired up.
diff --git a/pages/topics/18.01.StarterProjects.md
b/pages/topics/18.01.StarterProjects.md
index c5e4028a4f..5270e1e639 100644
--- a/pages/topics/18.01.StarterProjects.md
+++ b/pages/topics/18.01.StarterProjects.md
@@ -1,3 +1,8 @@
+---
+title: "Starter Projects"
+slug: StarterProjects
+---
+
# Starter Projects
Apache Juneau provides three minimal, clone-and-go **"Hello World" starter
projects** — one per
diff --git a/sidebars.ts b/sidebars.ts
index 18eec85119..3cedd89034 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -2106,6 +2106,18 @@ const sidebars: SidebarsConfig = {
},
],
},
+ {
+ type: 'category',
+ label: '17. Dependency Management',
+ collapsed: true,
+ items: [
+ {
+ type: 'doc',
+ id:
'topics/17.01.DependencyManagement',
+ label: '17.1.
Dependency Management (BOM & Bundles)',
+ },
+ ],
+ },
{
type: 'category',
label: '18. Starter Projects',
