docs(templates): add which-template-system decision guide (G1)#86
Merged
Conversation
The repo ships two parallel canonical template surfaces with confusingly similar names: `cv.presets.*` (the "classic" v1.6 rebuilt surface) and `cv.v2.presets.*` (the layered architecture). New contributors and downstream callers cannot tell which one to use without reading both the v1-classic and v2-layered READMEs end-to-end and decoding the cross-references between them. The new page (`docs/templates/which-template-system.md`) is the decision guide: - Section 0 pins terminology once — "classic" vs "layered" — and maps it to the actual package names and ADR references (0011 / 0015). - Section 1 is the status matrix: every template surface plus the canonical DSL labelled Recommended / Supported / Legacy / Internal, with the "Use for new code?" column called out separately from the "Will exist in 2.0?" column. - Section 2 is a decision tree for "I want to render X". - Section 3 is the migration table: 14 classic CV presets → their same-named v2-layered replacement + paired cover-letter preset, plus the InvoiceV1/V2, ProposalV1/V2, WeeklyScheduleV1 inventory. - Section 4 is the 1.x → 2.0 deprecation inventory naming every type slated for removal (GraphCompose.pdf, PdfComposer, MainPageCV, com.demcha.compose.v2.*, the entire cv.presets.* package, etc.) so callers can audit their own imports. - Section 5 cross-links to ADRs, v1-classic / v2-layered docs, and the migration roadmaps already in the repo. CanonicalSurfaceGuardTest.publicMarkdownDocsShouldAvoidLegacySurfaceOutsideHistoricalAuditNotes allowlist updated to permit the new page — same allowlist mechanism the v1.5 → v1.6 migration log already uses, and the new doc is the same kind of artifact (audit / migration log naming retired surface). CHANGELOG entry added to v1.6.6 — Planned under a new "### Documentation" subsection. Verification: - ./mvnw test -pl . -Dtest='CanonicalSurfaceGuardTest,DocumentationCoverageTest,DocumentationExamplesTest,VersionConsistencyGuardTest' -> 30 tests, 0 failures, 0 errors (~24s) - ./mvnw test -pl . -> 1023 tests, 0 failures, 0 errors (~55s)
DemchaAV
force-pushed
the
docs/which-template-system
branch
from
be1934c to
2fc9154
Compare
This was referenced May 31, 2026
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 G1 (
docs/which-template-system) from the 1.6.5→1.7 readiness taskboard — the onboarding clarity work for 1.6.6's first Maven Central debut.GraphCompose ships two parallel canonical template surfaces with confusingly similar names:
cv.presets.*— the "classic" v1.6 rebuilt surface (CvSpec+CvBuilder+BusinessTheme)cv.v2.presets.*— the layered architecture (data/theme/components/widgets/presets +CvDocument, recommended)To pick correctly, a new contributor today reads the
v1-classic/andv2-layered/READMEs back-to-back and decodes the cross-references — including the warning at the top ofv1-classic/README.mdthat this isn't the same axis as the package name'sv2suffix. That's exactly the friction this page removes.The new page —
docs/templates/which-template-system.mdcv.presets.*documented underv1-classic/; "layered" =cv.v2.*documented underv2-layered/. Maps to ADR-0011 and ADR-0015.classicCV presets → same-namedcv.v2.presets.*replacement + paired*Letter. Plus Invoice / Proposal V1↔V2 and the WeeklySchedule V1-only note.GraphCompose.pdf(...),PdfComposer,MainPageCV,MainPageCvDTO,ModuleYml,TemplateBuilder,com.demcha.compose.v2.*, the entirecv.presets.*package, etc.) with the canonical-DSL replacement.Guard allowlist change
CanonicalSurfaceGuardTest.publicMarkdownDocsShouldAvoidLegacySurfaceOutsideHistoricalAuditNotesscans public docs for legacy API tokens and fails the build if it finds them anywhere outside the allowlist.The deprecation-inventory section (§4) intentionally names every retired type — that's the whole point of a deprecation inventory. Adding
docs/templates/which-template-system.mdtoPUBLIC_MARKDOWN_ALLOWLISTmatches the same precedent the v1.5 → v1.6 migration log already sets (it's the only other entry in the allowlist) and the in-code comment explains the contract.Verification
The new page is
binary-compat-irrelevant (zero code surface), but thebinary-compatCI job will still run and stay zelёный.Test plan
docs/templates/v1-classic/README.mdanddocs/templates/v2-layered/README.mdso anyone landing on either README is one click from the decision guide