docs(examples): reorganise gallery by maturity tier (G2)#87
Merged
Conversation
Wires up Track G2 from the v1.6.5→1.7 readiness taskboard. examples/README.md previously grouped the 26 examples by the GraphCompose release that introduced them (Built-in templates / Cinematic v1.5 / v1.5 feature showcases / v1.6 feature showcases / Public-API surface / Production patterns / Operational documents). That layout is useful as a release history but unhelpful for someone landing on the examples folder for the first time who needs to know "which one do I read first" or "is this still recommended for new code". The gallery now categorises by maturity / intent, in five tiers with the legend block introduced at the section header: 🚀 Start here — minimum-friction entry points 🧱 Core DSL — daily-driver features 📋 Templates recommended — v2 / layered template surfaces 🔧 Advanced SPI — production patterns + specialty SPIs 🗄️ Legacy — pre-rebuild surface, do not start new code Tier counts: 🚀 4 · 🧱 6 · 📋 4 · 🔧 8 · 🗄️ 4 = 26 examples (unchanged from before — no examples added or removed). All anchor IDs (#cv-single-template, #invoice-cinematic-v2, etc.) are preserved verbatim, so existing deep links from the canonical README, ADRs, and external sources continue to resolve. Only the gallery index is restructured; the detailed sections below the gallery are untouched. The 🗄️ Legacy tier description links to docs/templates/which-template-system.md (from G1) for the V1 → V2 migration path, so the two onboarding-clarity PRs cross-link naturally. Verification: - ./mvnw -B -ntp test -pl . -Dtest='CanonicalSurfaceGuardTest,DocumentationCoverageTest,DocumentationExamplesTest,VersionConsistencyGuardTest' -> 30 tests, 0 failures - ./mvnw -B -ntp -f examples/pom.xml clean compile -> BUILD SUCCESS (5.2s) CHANGELOG entry added to v1.6.6 — Planned under the existing ### Documentation subsection (alongside the G1 entry).
6 tasks
DemchaAV
added a commit
that referenced
this pull request
May 31, 2026
Wires up Track G3 from the v1.6.5→1.7 readiness taskboard — the third and final onboarding-clarity PR for the 1.6.6 Maven Central debut (after G1 which-template-system #86 and G2 examples-maturity #87). ADR-0003 defines the @internal annotation mechanism, but there has been no user-facing policy that tells callers: - What "Stable" actually promises across patch / minor / major. - Where Extension SPI sits and what the @beta annotation will mean once it lands. - That sealed hierarchies in Stable types can grow new permits in minor releases — and what that means for exhaustive switch code. - How long a @deprecated element stays before it goes away. - Which package belongs to which tier without reading Javadoc per element. docs/api-stability.md is the user-facing policy: §1 Stability tiers — Stable / Extension SPI / Internal / Experimental with marker, scope, breaking-change rules, and the explicit promise each tier carries. §2 Sealed hierarchies — additive permits must degrade gracefully without default-branch failures; CHANGELOG names every new public permit; @internal sealed types are explicitly outside the policy. §3 Deprecation window — ≥ 1 minor release with @deprecated for Stable / Extension SPI; removed in next major (Stable) or next minor with CHANGELOG callout (Extension SPI). Internal / Experimental: no window required. §4 Per-package tier — lookup table covering com.demcha.compose.* plus the legacy packages. §5 Anti-policy — what we explicitly do NOT promise (pixel- stable PDFs, bit-stable bytes, sealed-permit exhaustiveness in Stable across minor releases). §6 References — cross-links to ADR-0003 / 0004 / 0011 / 0015 and the architecture guard tests that pin the policy in code. CanonicalSurfaceGuardTest.PUBLIC_MARKDOWN_ALLOWLIST gains a new entry for docs/api-stability.md (same audit-log precedent as the G1 which-template-system page and the v1.5→v1.6 migration log) — the §4 tier table and §3 deprecation example name retired legacy types on purpose. Cross-links from §1 and §4 point at G1's which-template-system page for the template-surface migration path; the two pages reference each other naturally (templates page covers template surfaces; this page covers everything else). Verification: - ./mvnw -B -ntp test -pl . -Dtest='CanonicalSurfaceGuardTest,DocumentationCoverageTest,DocumentationExamplesTest,VersionConsistencyGuardTest' -> 30 tests, 0 failures, 0 errors (~19s) CHANGELOG entry added to v1.6.6 — Planned under the existing ### Documentation subsection alongside G1 and G2.
DemchaAV
added a commit
that referenced
this pull request
May 31, 2026
Wires up Track G3 from the v1.6.5→1.7 readiness taskboard — the third and final onboarding-clarity PR for the 1.6.6 Maven Central debut (after G1 which-template-system #86 and G2 examples-maturity #87). ADR-0003 defines the @internal annotation mechanism, but there has been no user-facing policy that tells callers: - What "Stable" actually promises across patch / minor / major. - Where Extension SPI sits and what the @beta annotation will mean once it lands. - That sealed hierarchies in Stable types can grow new permits in minor releases — and what that means for exhaustive switch code. - How long a @deprecated element stays before it goes away. - Which package belongs to which tier without reading Javadoc per element. docs/api-stability.md is the user-facing policy: §1 Stability tiers — Stable / Extension SPI / Internal / Experimental with marker, scope, breaking-change rules, and the explicit promise each tier carries. §2 Sealed hierarchies — additive permits must degrade gracefully without default-branch failures; CHANGELOG names every new public permit; @internal sealed types are explicitly outside the policy. §3 Deprecation window — ≥ 1 minor release with @deprecated for Stable / Extension SPI; removed in next major (Stable) or next minor with CHANGELOG callout (Extension SPI). Internal / Experimental: no window required. §4 Per-package tier — lookup table covering com.demcha.compose.* plus the legacy packages. §5 Anti-policy — what we explicitly do NOT promise (pixel- stable PDFs, bit-stable bytes, sealed-permit exhaustiveness in Stable across minor releases). §6 References — cross-links to ADR-0003 / 0004 / 0011 / 0015 and the architecture guard tests that pin the policy in code. CanonicalSurfaceGuardTest.PUBLIC_MARKDOWN_ALLOWLIST gains a new entry for docs/api-stability.md (same audit-log precedent as the G1 which-template-system page and the v1.5→v1.6 migration log) — the §4 tier table and §3 deprecation example name retired legacy types on purpose. Cross-links from §1 and §4 point at G1's which-template-system page for the template-surface migration path; the two pages reference each other naturally (templates page covers template surfaces; this page covers everything else). Verification: - ./mvnw -B -ntp test -pl . -Dtest='CanonicalSurfaceGuardTest,DocumentationCoverageTest,DocumentationExamplesTest,VersionConsistencyGuardTest' -> 30 tests, 0 failures, 0 errors (~19s) CHANGELOG entry added to v1.6.6 — Planned under the existing ### Documentation subsection alongside G1 and G2.
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
1 participant
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.
Summary
Wires up Track G2 (
docs/examples-maturity-index) from the 1.6.5→1.7 readiness taskboard — the second of three onboarding-clarity PRs for the 1.6.6 Maven Central debut (after G1 #86).examples/README.mdpreviously grouped the 26 examples by the release that introduced each one (Built-in templates / Cinematic v1.5 / v1.5 feature showcases / v1.6 feature showcases / Public-API surface / Production patterns / Operational documents). Useful as a release history; less useful for someone landing on the folder for the first time who needs to know "which one do I read first?" or "is this still recommended for new code?".What changes
The gallery now categorises by maturity / intent, in five tiers introduced by a legend block at the section header:
Total = 26 examples (unchanged — no examples added or removed). Tier counts double-check the migration is complete.
All anchor IDs (
#cv-single-template,#invoice-cinematic-v2, etc.) are preserved verbatim, so existing deep links from the canonical README, ADRs, and external sources continue to resolve. Only the gallery index is restructured; the detailed sections below the gallery are untouched.The 🗄️ Legacy tier description links to
docs/templates/which-template-system.md(from G1) for the V1 → V2 migration path, so the two onboarding-clarity PRs cross-link naturally.Notable categorisation calls
Invoice — cinematic V2moved into 🚀 Start here (it's the recommended invoice path; the previous "Cinematic templates v1.5" tier was misleading — "cinematic" is the theme, not the maturity).Module-first Profilestays in 🚀 Start here — it's the DSL-direct authoring entry point, not a template, and beginners benefit from seeing both the template and DSL paths early.Transformssits in 🧱 Core DSL rather than 🔧 Advanced SPI —rotate/scale/zIndexare part of the daily-driver DSL surface, not specialty SPI. Shape clipping and barcodes are SPI; transforms aren't.Custom Business Themesits in 📋 Templates recommended — it's the theme-customisation entry point for V2 built-in templates, naturally adjacent to the gallery examples.WeeklyScheduleTemplateV1sits in 🗄️ Legacy — there's no V2 yet and the V1 API will be re-shaped before 2.0 (called out in the row description, mirrored from the G1 doc).Verification
The taskboard G2 gate is
doc-guard + smoke compile; both green.CHANGELOG entry added to
v1.6.6 — Plannedunder the existing### Documentationsubsection alongside the G1 entry.Test plan
CanonicalSurfaceGuardTest)docs/templates/which-template-system.mdso the two onboarding pages reference each other in both directions