You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@grails.apache.org by "jamesfredley (via GitHub)" <gi...@apache.org> on 2026/05/03 12:00:08 UTC
[PR] Support multiple concurrent Grails majors on the home, downloads, and documentation pages [grails-static-website]
jamesfredley opened a new pull request, #489:
URL: https://github.com/apache/grails-static-website/pull/489
## Summary
This PR refactors the website so multiple current Grails majors are first-class citizens instead of a single "latest" with everything else in dropdowns. Today the redesigned home, downloads, and documentation pages render side-by-side cards for **7.0.10 + 7.1.0**; once 8.0.0 ships, the same pages render **7.0.X + 7.1.X + 8.0.0** automatically with no template edits required.
The PR also moves five hard-coded companion plugin versions (Spring Security, Redis, Quartz, GitHub Actions, Gradle Publish) out of `DownloadPage.groovy`'s method-local constants into a structured `companionArtifacts:` block in `conf/releases.yml`, and replaces this repo's hand-rolled regex version parser with grails-core's canonical `GrailsVersion` class so we no longer maintain our own.
## Behavior at a glance
| Surface | Today (before) | Today (after) | Once 8.0.0 ships |
|---|---|---|---|
| Home page hero | One CTA pinned to `[%latest]` | Two side-by-side cards (7.0 + 7.1) | Three cards (7.0 + 7.1 + 8.0), auto |
| /download.html | One stable card; rest in dropdowns | Card grid, one per active minor line | Grid scales to N cards |
| /documentation.html | Same single-card pattern | Mirrored card grid | Same auto-scaling |
| Pre-release section | Single, only if newer than stable | Per-major, suppressed once stable supersedes it | Apache release-policy compliance |
| Plugin versions | 5 hard-coded constants in DownloadPage | `companionArtifacts:` block in releases.yml | Per-major, ready for `'8':` |
| Version parsing | 166 lines of local regex code | Delegated to grails-core's GrailsVersion | Zero local maintenance |
| Release workflow | recordRelease (core only) | recordRelease + new recordCompanionRelease task and workflow | Each plugin bumps independently |
## Active-minor-line rule
`SiteMap.activeMinorLines` always includes every minor line of the highest stable major. If that major has fewer than two minor lines (e.g. just after 8.0.0 ships), it also includes every minor line of the previous major so the page never shrinks to a single card. Once the new major grows a second minor (8.1.0), the previous major's lines roll off automatically. 13 SiteMapSpec scenarios cover today, 8.0.0-ship-day, and 8.1.0-ship-day transitions, pre-release suppression, brand-new-major pre-releases, and legacy `releases:` key compatibility.
## Apache release-policy compliance
Stable releases (`X.Y.Z`) only ever appear on the home-page hero. Apache-released milestones and release candidates (`X.Y.Z-M1`, `X.Y.Z-RC1`) are intentionally absent from the home page but always linked from /download.html and /documentation.html under their own "Pre-release (Apache-released)" section, since they are official Apache releases published to Maven Central.
## Schema migration safety
`conf/releases.yml` is restructured into two top-level sections:
- `companionArtifacts:` (new) - per-major plugin entries with their own versions and Apache mirror sub-paths.
- `coreReleases:` (renamed from `releases:`) - the historical flat list of every Grails core release.
`SiteMap.versions()` accepts either `coreReleases:` (canonical) or the legacy `releases:` key for one release cycle so external tooling that still writes the old schema keeps working during the migration window. `coreReleases:` is intentionally placed last in the file so `RecordReleaseTask`'s plain append-to-end-of-file continues to work without structural YAML parsing.
## Commit-by-commit walkthrough
Reviewers can step through the PR commit-by-commit; each commit is a self-contained logical unit:
1. Add grails-datastore-core dependency (plus grails-bom platform for transitive resolution)
2. Replace local SoftwareVersion/Snapshot with ReleaseVersion facade over grails-core GrailsVersion (also fixes mis-labelling of dash-style pre-releases on the docs page)
3. Migrate releases.yml to structured schema with `releases:` alias
4. Move hard-coded companion plugin versions out of DownloadPage into `companionArtifacts:`
5. Add SiteMap multi-major helpers (`latestStablePerMinorLine`, `latestPreReleasePerMajor`, `highestStablePerMajor`, `activeMinorLines`)
6. Redesign Downloads page with multi-version card grid plus new CSS
7. Mirror the redesign on Documentation page
8. Render multi-version hero cards on the home page
9. Add `recordCompanionRelease` Gradle task plus matching release-companion workflow
## Vendoring contract preserved
The vendored `buildSrc/src/main/groovy/grails/doc/dropdown/SoftwareVersion.groovy` and `Snapshot.groovy` are intentionally untouched. Per `buildSrc/VENDOR.md` they are byte-identical copies from `apache/grails-core 7.2.x` and any local modification would break the documented re-vendor procedure. Only this repo's own `website.model.documentation.SoftwareVersion` and `Snapshot` were replaced.
## Verification
- `./gradlew build` succeeds end-to-end.
- `./gradlew :buildSrc:test` runs 72 tests; 71 pass. The single failure (`ValidateGuidesTaskSpec > shape mode rejects a non-40-char SHA`) is pre-existing on master and unrelated to this PR - verified by running the same test against master before any changes were made.
- 51 new test cases added: 38 in ReleaseVersionSpec (covering every legacy version format in releases.yml plus ordering edge cases) and 13 in SiteMapSpec (covering the multi-major helpers and the today, 8.0.0-ship-day, and 8.1.0-ship-day transitions).
- `recordCompanionRelease` smoke-tested by bumping grails-redis 5.0.1 to 5.0.2 and confirming the diff is exactly one line with all surrounding comments and indentation preserved.
- Rendered `build/temp/download.html` contains 2 .guide-group cards inside one .release-grid (7.0.10 + 7.1.0) with all 5 companion plugin URLs identical to the legacy hard-coded output.
- Rendered `build/temp/documentation.html` contains 11 cards across 2 .release-grid containers and 4 section headers.
- Rendered `build/dist/index.html` contains exactly one .hero-cards container with two .hero-card boxes.
Assisted-by: claude-code:claude-opus-4-7
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@grails.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Support multiple concurrent Grails majors on the home, downloads, and documentation pages [grails-static-website]
Posted by "jdaugherty (via GitHub)" <gi...@apache.org>.
jdaugherty merged PR #489:
URL: https://github.com/apache/grails-static-website/pull/489
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@grails.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Support multiple concurrent Grails majors on the home, downloads, and documentation pages [grails-static-website]
Posted by "jamesfredley (via GitHub)" <gi...@apache.org>.
jamesfredley commented on PR #489:
URL: https://github.com/apache/grails-static-website/pull/489#issuecomment-4366179070
## Visual before / after
Captured via Playwright at 1440x900 viewport, full-page scrolling. **Before** screenshots are from the live site at https://grails.apache.org/. **After** screenshots are from a local build of this branch served over `http://localhost`.
The screenshot images themselves live on the temporary [`pr-489-screenshots`](https://github.com/apache/grails-static-website/tree/pr-489-screenshots) branch and that branch can be deleted once this PR merges.
---
### Home page
| Before (live grails.apache.org) | After (this PR) |
|---|---|
| <img alt="home page before" src="https://github.com/apache/grails-static-website/raw/pr-489-screenshots/before-home.png" /> | <img alt="home page after" src="https://github.com/apache/grails-static-website/raw/pr-489-screenshots/after-home.png" /> |
The single "Documentation / Download" CTA pinned to `[%latest]` is replaced with two side-by-side hero cards (one per active stable minor line: 7.1.0 and 7.0.10). Once 8.0.0 ships, the same template renders three cards automatically with no edit to `pages/index.html` required.
---
### Downloads page
| Before (live grails.apache.org) | After (this PR) |
|---|---|
| <img alt="downloads page before" src="https://github.com/apache/grails-static-website/raw/pr-489-screenshots/before-download.png" /> | <img alt="downloads page after" src="https://github.com/apache/grails-static-website/raw/pr-489-screenshots/after-download.png" /> |
The legacy two-column layout collapsed every release into the left column with one prominent "Latest Version" card and the rest in a `<select>` dropdown. The redesigned layout features a "Current Releases" card grid (one card per active minor line, today: 7.0.10 and 7.1.0), a separate "Pre-release (Apache-released)" section for milestone / RC artifacts when present (suppressed today because 7.1.0-RC1 was superseded by 7.1.0 stable), the "Older Versions" dropdown, and a "Get Started" footer with Forge + SDKMAN install instructions.
The companion plugin downloads (Spring Security, Redis, Quartz, GitHub Actions, Gradle Publish) are now driven by data in `conf/releases.yml` rather than five hard-coded constants in `DownloadPage.groovy`. Each card iterates `companionArtifactsFor(major)` so plugins for Grails 8 will surface automatically once that section is populated in `releases.yml`.
---
### Documentation page
| Before (live grails.apache.org) | After (this PR) |
|---|---|
| <img alt="documentation page before" src="https://github.com/apache/grails-static-website/raw/pr-489-screenshots/before-documentation.png" /> | <img alt="documentation page after" src="https://github.com/apache/grails-static-website/raw/pr-489-screenshots/after-documentation.png" /> |
Same multi-version layout pattern as the downloads page. Each active minor line gets its own card with User Guide + API Reference links. The three older-version dropdowns (Single-page, User Guide, API Reference) and the module category boxes (GORM, Security, Upgrade, Testing, Views, Async, Database, Redis) move to a "Modules" section in a two-column footer.
Also note that the labels on the cards now say "Latest Version (X.Y.Z) Documentation" for both 7.0.10 and 7.1.0 - acceptable for the first cut since the version number itself communicates which is which, but a UX follow-up could differentiate "Stable" vs "Latest Stable" once the multi-version pattern is live.
---
### Apache release-policy compliance
Stable releases (`X.Y.Z`) only ever appear on the home-page hero - Apache-released milestones and release candidates (`X.Y.Z-M1`, `X.Y.Z-RC1`) are intentionally absent there but always linked from `/download.html` and `/documentation.html` under their own "Pre-release (Apache-released)" section once one exists. The screenshots don't show this section because today's `releases.yml` has no pre-release newer than the stable that supersedes it; the rendering path is exercised by `SiteMapSpec` ("latestPreReleasePerMajor includes a pre-release that has not been superseded by stable" / "exposes a brand new majors first M/RC even when no stable exists for that major").
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@grails.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org