Expands #454 with the actual inventory, after the same defect had to be fixed three times in a row across three files.
The gap
cut-release.ps1 regenerates exactly one file under assets/readme/:
| step |
regenerates |
Run-ShowcaseSync |
web/showcase/** — the site gallery |
Render-ReadmeBanner |
assets/readme/repository_showcase_render.png |
| — |
nothing else under assets/readme/ |
There are 82 committed files there (68 under examples/, 13 images, one logo). Every one except the hero banner is frozen at whatever commit last touched it by hand. They are linked from the root README and the examples gallery, so a reader clicking through gets whatever was true that day.
What is actually stale, and what only looks stale
I scanned every committed PDF for embedded versions and codenames. The results split three ways, and conflating them would overstate the problem.
1. A live version stamp that was wrong — fixed in #460.
assets/readme/examples/engine-deck-v2.pdf rendered the build version. Its page one is the hero banner, so it carried v2.0.0, GRAPHCOMPOSE 2.0 / MODULE-FIRST and a module row with no render-pptx — the same defect #458 fixed in the source and the PNG, surviving in a third file.
Currently correct after the release: engine-deck.pdf (v2.1.0 / twinned), maven-banner.pdf (v2.1.0), repository_showcase_render.png. All three were refreshed by hand, one per incident.
2. Example content that names an old version — not a stamp, but it dates the demo.
These are fictional documents whose text happens to mention a release. Nothing renders them wrong; they simply read oddly on a 2.1 project:
master-showcase.pdf — the kitchen-sink flagship is a mock release plan for "v1.5 — 'intuitive' release", complete with "Tag v1.5.0 on main once develop is merged". Six releases old, and it is one of the most-linked examples.
canvas-layer-showcase.pdf — "Issued for shipping the v1.6 expressive release".
inline-highlight-chips.pdf — "Run ./mvnw verify then tag v1.9.0 to publish graph-compose-emoji".
3. Not a problem at all.
inline-code-column-wrap.pdf shows io.github.demchaav:graph-compose:1.9.0 and org.junit.jupiter:junit-jupiter:5.10.2 — those are the demo table's cells, illustrating inline-code chips in a narrow column. The versions are the subject matter.
cv-modern-professional.pdf / cv-classic-serif.pdf match "cinematic", but it is résumé prose ("cinematic covers, pull quotes"), not a release codename.
Why it recurs
Two separate things have to be true, and neither is enforced:
- Nothing regenerates the assets, so a source fix does not reach the file a reader opens.
- A version-stamping asset can only be rendered correctly during a cut.
develop sits on X.Y.(Z+1)-SNAPSHOT between releases, so regenerating at any other moment bakes a -SNAPSHOT string into a public file. Every refresh in this release had to override the filtered banner.properties by hand to get 2.1.0.
Directions
- Add an
assets/readme/** refresh step to cut-release.ps1, beside Render-ReadmeBanner, which already solves this for one file. It runs after the version bump, which is the only moment a version-stamped asset renders correctly. Verify under -DryRun, -PostReleaseOnly and -SkipShowcase — the v1.6.5 lesson.
- Or stop stamping the build version into assets. The pill is the only place it earns its keep; the kicker and graph label could drop the number entirely and never rot again.
- Guard it: a test that renders the version-bearing examples and asserts the committed copy matches would turn this into a red build instead of a reader noticing.
- Separately, refresh the category-2 demo content so the flagship example is not a 1.5-era release plan.
Expands #454 with the actual inventory, after the same defect had to be fixed three times in a row across three files.
The gap
cut-release.ps1regenerates exactly one file underassets/readme/:Run-ShowcaseSyncweb/showcase/**— the site galleryRender-ReadmeBannerassets/readme/repository_showcase_render.pngassets/readme/There are 82 committed files there (68 under
examples/, 13 images, one logo). Every one except the hero banner is frozen at whatever commit last touched it by hand. They are linked from the root README and the examples gallery, so a reader clicking through gets whatever was true that day.What is actually stale, and what only looks stale
I scanned every committed PDF for embedded versions and codenames. The results split three ways, and conflating them would overstate the problem.
1. A live version stamp that was wrong — fixed in #460.
assets/readme/examples/engine-deck-v2.pdfrendered the build version. Its page one is the hero banner, so it carriedv2.0.0,GRAPHCOMPOSE 2.0 / MODULE-FIRSTand a module row with norender-pptx— the same defect #458 fixed in the source and the PNG, surviving in a third file.Currently correct after the release:
engine-deck.pdf(v2.1.0/twinned),maven-banner.pdf(v2.1.0),repository_showcase_render.png. All three were refreshed by hand, one per incident.2. Example content that names an old version — not a stamp, but it dates the demo.
These are fictional documents whose text happens to mention a release. Nothing renders them wrong; they simply read oddly on a 2.1 project:
master-showcase.pdf— the kitchen-sink flagship is a mock release plan for "v1.5 — 'intuitive' release", complete with "Tag v1.5.0 on main once develop is merged". Six releases old, and it is one of the most-linked examples.canvas-layer-showcase.pdf— "Issued for shipping the v1.6 expressive release".inline-highlight-chips.pdf— "Run ./mvnw verify then tag v1.9.0 to publish graph-compose-emoji".3. Not a problem at all.
inline-code-column-wrap.pdfshowsio.github.demchaav:graph-compose:1.9.0andorg.junit.jupiter:junit-jupiter:5.10.2— those are the demo table's cells, illustrating inline-code chips in a narrow column. The versions are the subject matter.cv-modern-professional.pdf/cv-classic-serif.pdfmatch "cinematic", but it is résumé prose ("cinematic covers, pull quotes"), not a release codename.Why it recurs
Two separate things have to be true, and neither is enforced:
developsits onX.Y.(Z+1)-SNAPSHOTbetween releases, so regenerating at any other moment bakes a-SNAPSHOTstring into a public file. Every refresh in this release had to override the filteredbanner.propertiesby hand to get2.1.0.Directions
assets/readme/**refresh step tocut-release.ps1, besideRender-ReadmeBanner, which already solves this for one file. It runs after the version bump, which is the only moment a version-stamped asset renders correctly. Verify under-DryRun,-PostReleaseOnlyand-SkipShowcase— the v1.6.5 lesson.