Skip to content

Committed README assets have no regeneration path — 1 of 82 is refreshed on release #461

Description

@DemchaAV

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:

  1. Nothing regenerates the assets, so a source fix does not reach the file a reader opens.
  2. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingexamplesRunnable examples / galleryrelease2.0 release-cycle task

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions