Skip to content

Spring Boot 3.2 and older predate the Antora component: decide whether to ingest the pre-Antora layout at all #138

Description

@amondnet

The documented floor for boot is 3.3.0, and the reason is structural rather than incidental: the
Antora component does not exist before it.

Evidence (probed 2026-09-16)

v3.2.12  spring-boot-project/spring-boot-docs/src/docs/  ->  asciidoc/          (only)
v3.3.0   spring-boot-project/spring-boot-docs/src/docs/  ->  antora/, dokkatoo/

3.2.x and older ship src/docs/asciidoc — a flat AsciiDoc tree with no antora.yml, no
modules/ROOT, no nav, and no component version. Nothing in the current pipeline can classify it:
ADR-0002 makes Antora the loader, and @antora/content-classifier needs a component descriptor to
produce a page at all.

Why this is a decision, not a task

Supporting it means a second ingestion path that does not go through Antora: resolve
include::/ifdef by hand with Asciidoctor alone, invent the page-to-path mapping Antora would have
produced, and re-point every xref: that the corpus writes in pre-Antora form. That path would share
only markdown-converter.ts with the pipeline that exists, and it would be the only part of the
repository whose output layout is not derived from a component descriptor.

Against that: 3.2.x went out of OSS support in 2024, and everything from 3.3.0 on is already
published (47 versions in catalog.json).

Options

  1. Do not support it. Keep 3.3.0 as the floor, and say so where a user would look — the README
    support table, release-pipeline, and the message fetch-upstream.ts prints when a version falls
    outside every era. Close the door explicitly instead of leaving it implicit in an era range.
  2. A separate pre-Antora ingestion path, only if someone actually asks for 3.2.x or older. The
    README's backfill policy already routes such a request through an issue, so demand would be
    visible before the work starts.
  3. Take the published HTML instead of the sources for those versions. Cheapest of the three, but
    it breaks the provenance chain every other release has — manifest.json records an upstream
    commit, and a scrape cannot.

Recommendation

Option 1 until a request exists, with the floor stated as a product decision rather than a
limitation of the current code. If it is adopted, this issue closes by documenting it in the README
support table and adding a short ADR, since ADR-0004 explains why eras exist but not why the oldest
one starts where it does.

Done when

The floor is documented as a decision, or option 2 is chosen and filed as its own implementation
issue.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions