Skip to content

Surface companion plugins on downloads page when target Grails major has not yet shipped#501

Merged
jamesfredley merged 1 commit intomasterfrom
surface-orphan-companion-plugins-on-downloads-page
May 3, 2026
Merged

Surface companion plugins on downloads page when target Grails major has not yet shipped#501
jamesfredley merged 1 commit intomasterfrom
surface-orphan-companion-plugins-on-downloads-page

Conversation

@jamesfredley
Copy link
Copy Markdown
Contributor

Summary

  • Adds a new Plugins for upcoming Apache Grails releases section to /download.html that lists Apache-released companion plugins whose target Grails major has no entry yet in coreReleases: (e.g. the existing companionArtifacts['8'] -> grails-publish 1.0.0-M1 block).
  • Introduces SiteMap.orphanCompanionMajors(File) to compute those orphan majors (descending, empty companion lists skipped).
  • Adds DownloadPage.renderCompanionsOnlyCard(major, companions) - a card with the same guide-group / release-grid visual vocabulary as the existing sections, minus the core Source / Binary / Wrapper / Grails Release Notes block (since that core release does not exist yet).

Why

download.html iterates Grails majors via activeMinorLines() and latestPreReleasePerMajor(), both of which read only coreReleases:. That meant a companion plugin published ahead of its target core (e.g. grails-publish 1.0.0-M1 for the upcoming Grails 8) was silently invisible on the downloads page until Grails 8 shipped its first milestone. This PR closes that gap.

Auto-convergence (no future YAML edits)

The moment any release for an orphan major (stable, milestone, or RC) lands in coreReleases::

  • orphanCompanionMajors() drops the major.
  • The new section disappears (or shrinks to other orphans).
  • The existing per-major card in Current Releases or Pre-release (Apache-released) automatically picks up the same companions through companionArtifactsFor().

No manual YAML migration needed at release time.

Section ordering

```
Current Releases
Pre-release (Apache-released)
Plugins for upcoming Apache Grails releases <- NEW
Older Versions
Get Started
```

Test coverage

6 new `SiteMapSpec` cases mirror the existing `companionArtifactsFor` tests (`@TempDir` + `releasesFile()` helper):

  1. empty when no `companionArtifacts:` block exists
  2. empty when every companion major has a stable core release
  3. empty when the companion major has only a pre-release in `coreReleases:` (existing pre-release card handles it)
  4. returns the major when a companion exists but no core release of any kind exists
  5. returns multiple majors in descending order
  6. skips majors whose companion list is empty

All 6 pass. Pre-existing `ValidateGuidesTaskSpec > shape mode rejects a non-40-char SHA` failure exists on `master` independently of this change.

Verification

  • `./gradlew :buildSrc:test` -> all SiteMapSpec tests green.
  • `./gradlew build` -> succeeds.
  • Inspected `build/dist/download.html` rendered output: new section present in correct position, card titled Apache Grails 8 Plugins, links resolve to `apache-grails-publish-1.0.0-M1-src.zip` plus `.sha512` / `.asc` on `downloads.apache.org`, release notes -> `apache/grails-gradle-publish/releases/tag/v1.0.0-M1`.

Scope notes

  • Download page only. `DocumentationPage` does not currently render companion artifacts at all, so applying the same orphan logic there would be a new responsibility for that page; out of scope here.
  • No `releases.yml` schema change. The orphan-vs-attached distinction is inferred from existing data; nothing in the YAML moves when Grails 8 ships.

…has not yet shipped

Apache-released companion plugins (e.g. grails-publish 1.0.0-M1 under
companionArtifacts['8']) used to be invisible on download.html until at
least one matching core release landed in coreReleases, because the page
iterates majors via activeMinorLines / latestPreReleasePerMajor, both of
which read only coreReleases.

Add a new 'Plugins for upcoming Apache Grails releases' section between
the 'Pre-release (Apache-released)' grid and 'Older Versions'. The section
renders one card per major present in companionArtifacts but absent from
coreReleases (stable or pre-release). The card lists each companion's
Source / SHA512 / ASC verification links plus a release-notes link, and
omits the core source / binary / wrapper block that doesn't yet exist.

The section is driven by a new SiteMap.orphanCompanionMajors helper that
returns those orphan majors in descending order, skipping empty companion
lists. Once any release for an orphan major (including a milestone or RC)
is appended to coreReleases, the major drops out of the helper and the
existing per-major card automatically picks up its companions through
companionArtifactsFor - no YAML edits needed.

Verified by 6 new SiteMapSpec cases covering empty, all-covered,
pre-release-covered, single orphan, multiple orphans (descending order),
and empty-companion-list scenarios. Verified by full build that download.html
renders the new section with the existing companionArtifacts['8'] entry.

Assisted-by: claude-code:claude-4-opus
Copilot AI review requested due to automatic review settings May 3, 2026 23:07
@jamesfredley jamesfredley merged commit 1606bad into master May 3, 2026
5 checks passed
@jamesfredley jamesfredley deleted the surface-orphan-companion-plugins-on-downloads-page branch May 3, 2026 23:08
@jamesfredley jamesfredley review requested due to automatic review settings May 3, 2026 23:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant