feat: Read supported versions from the Hub, including nightly - #923
Open
lfrancke wants to merge 5 commits into
Open
feat: Read supported versions from the Hub, including nightly#923lfrancke wants to merge 5 commits into
lfrancke wants to merge 5 commits into
Conversation
Regenerates the supported-versions.adoc partials of the product operators from the Stackable Hub API for released docs versions. Nightly keeps the hand-maintained partials since the Hub only knows released data. Responses are cached in the Antora cache dir; the build never fails and never emits warnings when the Hub is unreachable (the production playbook fails builds on warnings). Parked until the Hub exposes the next (unreleased) SDP release: then nightly can be synced from it as well and the operator repos only need to be touched once (delete partials + adopt shared link bar).
Unparks the extension. It previously skipped nightly outright, on the grounds
that the Hub only knew released data, and was held back until a next SDP release
existed so the 16 operator repos would only need visiting once.
The Hub already models this properly, which removes the wait. Both
/api/v1/releases and /api/v1/components/{slug} return a shipped releases array
and a separate upcomingReleases array, and the Hub only exposes an upcoming
release once it is deliberately public -- provisional plans stay private. So
nightly reads upcomingReleases, and the window between a release shipping and the
next one being planned is a normal empty state rather than something to wait out.
It renders as an explicit "not been decided yet" line, and an unreleased list is
labelled provisional so a half-filled one cannot read as a commitment.
Also generates the partial when it is absent instead of only rewriting an
existing one. That is what lets the operator repos delete their copies: two
places include it, an operator's own index.adoc and this repo's platform-wide
operators:supported_versions.adoc, and both have to keep resolving. Since the
extension becomes load-bearing once those copies are gone, a missing partial with
no Hub data now gets a short unavailable note rather than nothing at all, so a
Hub outage still cannot break the build.
Moved from contentAggregated to contentClassified, because adding a file needs
the content catalog and partials are resolved later, when pages are converted.
Verified against a real only-dev build: 13 partials written, the undecided note
renders on both the operator page and the platform overview, addFile round-trips
retrievably in the catalog, and the released path still produces 26.7 as
3.2.2 / 3.1.6 (deprecated) / 3.0.6 (LTS) / 2.9.3 (deprecated), with an unknown
version correctly falling back to the repo copy.
Co-Authored-By: Claude <noreply@anthropic.com>
✅ Deploy Preview for stackable-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
…quests Three fixes from a review of this branch. Emit a partial even when the Hub has no data for a version and the repo has no copy to fall back on. renderPartial returned undefined for that case, and the caller then wrote nothing, which is safe only while every operator repo still ships a copy. Once the sweep deletes those, an include with no target fails the build - the exact failure this extension exists to prevent. The caller knows whether a copy exists, so it now says so. Resolve any docs version against upcomingReleases as well, not just nightly. A release branch is often cut and built before its SDP release ships, so those docs were getting nothing while the Hub had provisional data for that very release. 'Provisional' now follows from which array matched rather than from the docs version being nightly, which also collapses the nightly-versus-released split that caused both gaps. Time out Hub requests. A Hub that accepts the connection and never answers is not an error, so it stalled the build indefinitely instead of falling back to the cache. Co-Authored-By: Claude <noreply@anthropic.com>
Every operator index page introduces this partial with 'currently supports the versions listed below', so a bare sentence where the list should be reads as a contradiction: the page promises a list and then says nothing was decided. All three no-data cases now render as NOTE admonitions that say outright there is nothing to list, so the reader sees an aside explaining the absence rather than a sentence arguing with the one above it. A real version list is unchanged and still renders as a plain list. Co-Authored-By: Claude <noreply@anthropic.com>
lfrancke
marked this pull request as ready for review
August 21, 2026 13:48
xeniape
moved this from Development: Waiting for Review
to Development: In Review
in Stackable Engineering
xeniape
requested changes
Aug 31, 2026
xeniape
left a comment
xeniape
left a comment
Member
There was a problem hiding this comment.
I stopped the review for now because I didn't understand the business logic, will continue once that's answered.
Also some things I noticed, not sure if they were deliberate:
- The Hive 4 issues section disappears in this PR version
- The Druid Note also disappears
| lts: ' (LTS)', | ||
| deprecated: ' (deprecated)', | ||
| experimental: ' (experimental)', | ||
| preview: ' (preview)', |
Member
There was a problem hiding this comment.
Maybe I'm just seeing it for the first time, but do we actually use that one and how is it different from experimental?
| let written = 0 | ||
| for (const { version } of component.versions) { | ||
| for (const [moduleName, slug] of Object.entries(MODULE_TO_SLUG)) { | ||
| const existing = contentCatalog.getById({ |
Member
There was a problem hiding this comment.
I would like to rename that variable, "existing" isn't descriptive enough, what exists? Based on the call it should return the versions file, so maybe "versionsPartial" or "existingVersionsPartial"/"existingPartial"?
| const body = renderPartial({ | ||
| components, slug, version, logger, hasRepoCopy: Boolean(existing), | ||
| }) | ||
| if (!body) continue // the repo ships a copy and the Hub has nothing better |
Member
There was a problem hiding this comment.
I kind of don't understand the whole decision tree here. So for older branches where the versions partial exists, it still fetches the Hub information and overrides. Why not just keep the existing file in the older branches instead? The information there shouldn't change. It would also simplify the code, because that whole existing variable usage wouldn't be needed. (If I understood that correctly renderPartial itself also decides to skip the override if there is no related hub release, not sure when that is the case, seems no-op to me if existing file is used earlier). But maybe I misunderstand something.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This changes the documentation to NOT need the supported-version partials to be maintained manually anymore.
At build time it connects to the Stackable Hub to get the versions and writes the partials itself.
For unreleased versions (nightly) it says "not decided yet" (in nicer words).
See:
Note
When this is merged I'll go ahead and open PRs to delete the partial from every operator and then I assume some of the issue templates for version bumps need to be adjusted.