Why no extensions

A plugin with <extensions>true</extensions> is loaded into the build extension realm at project-load time — during Maven’s “Scanning for projects” phase, before the Model Builder runs property interpolation. This means the plugin’s <version> in the POM cannot be a ${property}; it must be a literal string.

For a single-repo reactor with one plugin, that constraint is manageable. For our cross-repo cascade (ike-tooling → ike-docs → ike-platform → consumers), it became toxic: every consumer POM had to carry the literal version of every extension plugin from upstream, the literal had to be kept in sync manually across repos, and routine version-property tooling (like ws:align-publish and versions:set-property) was structurally unable to maintain it.

The pain surfaced as IKE-Network/ike-issues#236 — pre-flight release checks repeatedly catching stale literals after upstream releases that the alignment tooling could not see.

Why no custom packaging

The historical reason for <extensions>true</extensions> here was to provide a custom <packaging>ike-doc</packaging> type for documentation modules — a packaging that produces a .zip of AsciiDoc sources as the primary artifact, with a lean lifecycle that skips compile/test phases.

Inspection revealed two problems with that frame:

1. The custom packaging produced a primary artifact nobody used. Across 43 <packaging>ike-doc</packaging> modules in ike-lab-documents, zero dependencies referenced <type>ike-doc</type>. Consumers exclusively used a parallel <classifier>asciidoc</classifier><type>zip</type> attachment (built by maven-assembly-plugin from the same source directory). Same content, two coordinates, redundant.
2. Custom packaging cannot serve hybrid modules. <packaging> is single-valued: a Java module that ships reference docs cannot be both jar and ike-doc. Every comparable docs-as-code project in the JVM ecosystem (Hibernate, Eclipse Collections, Vert.x, Quarkus, OptaPlanner, Apache projects) handles this via classifier attachments for exactly this reason. No project in the surveyed set invents a custom packaging type for documentation.

The architectural decision was therefore to retire <packaging>ike-doc</packaging> in favor of a classifier-canonical shape: <classifier>adoc</classifier><type>zip</type> attached to either a <packaging>pom</packaging> (doc-only) or <packaging>jar</packaging> (hybrid) primary. Activation is path-conditional on src/docs/asciidoc/ existence in ike-parent’s `doc-pipeline profile — not packaging type — so hybrid modules become first-class without per-module ceremony.

Why this is not Spring’s path

A natural objection: most large JVM projects (Spring, Apache projects, Quarkus) publish docs as static sites to gh-pages or CDN-hosted destinations rather than as Maven artifacts. Why not follow that pattern?

Examined point by point, those rationales do not transfer to our context:

• Continuous publication. Maven snapshots provide this — mvn deploy to a snapshot repo on every commit, snapshot semantics handle “latest” natively.
• Search-driven discovery. Static URLs are indexable; rsyncing HTML to a public web server downstream of a Maven artifact gives the same indexable URLs. knowledge.design already operates this way.
• Contributor friction. CI eliminates this — PR merge fires mvn deploy plus a post-deploy hook to rsync rendered output.
• CDN economics. Same as search — rsync to CDN works regardless of canonical-storage format.

What honestly remains as a non-Maven argument:

• Antora as a turnkey product. It does cross-version aggregation, theming, navigation, and CDN-friendly output as one coherent thing. Adopt Antora and you do not build any of that. Does not apply here — we have already built the equivalent pipeline (ike-parent’s render profiles, the Prince/FOP/XEP chains, `knowledge.design rsync deploy, the asciidoctor toolchain).
• ASF organizational policy. Apache projects cannot publish docs as Maven artifacts and call it done. A foundation rule, not an engineering reason. Does not apply outside ASF.
• Path dependency. Spring 1.0 shipped in 2003-04, before Maven Central was a viable documentation distribution channel. Spring’s current pipeline descends from choices that were rational then and are too costly to rip out now. Explains why-they-still-do-it but does not justify what a new project would choose today.

For our constraints — small team, cross-repo doc dependencies via topic libraries, an already-built rendering pipeline, and a standing commitment to artifact uniformity — staying inside the Maven artifact ecosystem is the rigorous choice. Every shipped artifact, code or documentation, goes through one pipeline: signed (Bouncy Castle GPG), versioned, deployed to Nexus, mirrorable, and reproducibly buildable years later. We hold every output to the same engineering standard — consistent signing, consistent distribution, consistent build lifecycle, consistent version control. The single-pipeline discipline is the standard we are protecting; uniformity across artifact classes is the point.

The classifier-canonical shape is fully Maven-canonical — it deploys to Nexus, signed, versioned. The choice between custom packaging and classifier is not a Maven-vs-non-Maven choice; both stay inside the Maven ecosystem. Custom packaging was buying an aesthetic type-system marker; classifier-canonical buys a single mechanism that handles doc-only and hybrid uniformly.

Tracking

• IKE-Network/ike-issues#321 — primary tracking issue (umbrella); subsumes #220, #236, #320.
• IKE-Network/ike-issues#216 — repo split that established the cross-repo boundary the extension realm was working around.
• Design note: dev-classifier-canonical-doc-shape in ike-lab-documents/topics/ (full Socratic discovery captured for posterity).