From 2fc9154b969143e7a4f62884005116e4dbc48551 Mon Sep 17 00:00:00 2001 From: DemchaAV Date: Sun, 31 May 2026 11:45:09 +0100 Subject: [PATCH] docs(templates): add which-template-system decision guide (G1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- CHANGELOG.md | 17 ++ docs/templates/which-template-system.md | 236 ++++++++++++++++++ .../CanonicalSurfaceGuardTest.java | 10 +- 3 files changed, 262 insertions(+), 1 deletion(-) create mode 100644 docs/templates/which-template-system.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 49f576df..837923d3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -36,6 +36,23 @@ JitPack continue to resolve through the existing coordinates. Javadoc now spells out the empty-list-clears semantics in prose, not only in the `@param` line. +### Documentation + +- **New decision guide: [`docs/templates/which-template-system.md`](docs/templates/which-template-system.md)** + (Track G1). The repo ships two parallel canonical template surfaces — + `cv.presets.*` (the "classic" v1.6 rebuild) and `cv.v2.presets.*` (the + layered architecture, recommended) — under confusingly similar names. + The new page pins the terminology once, gives a status matrix + (Recommended / Supported / Legacy / Internal) for every template + surface and the canonical DSL, walks a decision tree for new code, and + provides a preset-by-preset migration table from `classic` to + `layered` plus a 1.x → 2.0 deprecation inventory naming every type + scheduled for removal. `CanonicalSurfaceGuardTest` allowlist updated + so the deprecation-inventory section's literal mentions of + `GraphCompose.pdf(...)`, `PdfComposer`, etc. don't trip the + legacy-token scan (same allowlist class as the v1.5 → v1.6 migration + log already in there). + ## v1.6.5 — 2026-05-30 ### Templates v2 diff --git a/docs/templates/which-template-system.md b/docs/templates/which-template-system.md new file mode 100644 index 00000000..1a88bf9c --- /dev/null +++ b/docs/templates/which-template-system.md @@ -0,0 +1,236 @@ +# Which template system should I use? + +**Short answer.** For any **new** code on GraphCompose 1.6.x and later, use +the [**layered**](v2-layered/README.md) template surface +(`com.demcha.compose.document.templates.cv.v2.*`, paired with +`*Letter` cover-letter presets in `…coverletter.v2.*`). The older +[**classic**](v1-classic/README.md) surface still ships, still works, +and stays supported through the 1.x line, but **the layered surface is +the path forward** and is the only template family that will be in +GraphCompose 2.0. + +This page is the decision guide. It exists because the project ships +**two parallel canonical template surfaces** today, with confusingly +similar names, and a new contributor needs to know which one to read +and which one to write against. + +--- + +## 0. The naming, once + +The two surfaces have collided naming because the *codebase* and the +*docs* labelled them at different points in time: + +| What you'll see | Where it lives | What it actually is | +|---|---|---| +| **"Templates v2" (in commit messages, ADR 0011, package names like `cv.v2`)** | `com.demcha.compose.document.templates.cv.v2.*` | The **layered** architecture — *data / theme / components / widgets / presets*, paired with `CvDocument` builder. Recommended. | +| **"Templates v1.6" / "templates rebuild"** | `com.demcha.compose.document.templates.cv.presets.*` | The 1.6 rebuilt canonical surface — `CvSpec` + `CvBuilder` + presets + `BusinessTheme`. Still supported. | +| **Folder `docs/templates/v1-classic/`** | docs only | Documents the **non-layered** surface (`cv.presets.*`). The doc folder name is *not* the same axis as the package's `v2` suffix. | +| **Folder `docs/templates/v2-layered/`** | docs only | Documents the layered surface (`cv.v2.*`). | + +From here, this page uses one name per surface, consistently: + +- **`classic`** → `cv.presets.*`, documented in `docs/templates/v1-classic/` — pre-layered, still supported. +- **`layered`** → `cv.v2.*` + `coverletter.v2.*`, documented in `docs/templates/v2-layered/` — recommended. + +ADR references: [ADR-0011 templates-v2-architecture](../adr/0011-templates-v2-architecture.md) introduces the `classic` surface; +[ADR-0015 layered-template-architecture](../adr/0015-layered-template-architecture.md) introduces the `layered` one and supersedes 0011 for new template families. + +--- + +## 1. Status matrix + +| Surface | Status | Stability | Use for new code? | Will exist in 2.0? | First read | +|---|---|---|---|---|---| +| **Layered** (`cv.v2.*`, `coverletter.v2.*`) | **Recommended** | Stable (additive changes only) | ✅ Yes | ✅ Yes (canonical) | [v2-layered/quickstart](v2-layered/quickstart.md) | +| **Classic** (`cv.presets.*`, paired classic letter presets) | **Supported** | Stable, no new features | 🟡 Only if migrating an existing v1.5-era caller | ❌ Removed (full migration to layered) | [v1-classic/README](v1-classic/README.md) | +| **Built-in `*TemplateV2`** (Invoice / Proposal) | **Recommended** | Stable | ✅ Yes | ✅ Yes | [v1-classic/README](v1-classic/README.md) — InvoiceTemplateV2 / ProposalTemplateV2 sections (documented historically inside the v1-classic folder; pending a dedicated `built-ins/` section) | +| **Built-in `*TemplateV1`** (Invoice / Proposal / WeeklySchedule) | **Legacy** | Stable, no new features | ❌ No (use V2 versions; WeeklySchedule has no V2 yet) | ❌ Removed | (no top-level doc — see source Javadoc) | +| **Canonical DSL** (`GraphCompose.document()` + `DocumentSession` + `DocumentDsl`) | **Recommended** | Stable | ✅ Yes — required substrate for both template surfaces and direct authoring | ✅ Yes | [Main README — Hello world](../../README.md) | +| **Legacy PDF API** (`GraphCompose.pdf(...)`, `PdfComposer`, `com.demcha.compose.v2.*`, `com.demcha.templates.*`) | **Legacy** | Frozen — bug fixes only | ❌ No | ❌ Removed | `graphcompose-legacy-architect` skill (internal Claude / Codex artifact, not a repo page) | +| **Engine surface** (`com.demcha.compose.document.layout.*`, `com.demcha.compose.engine.*`, render handlers) | **Internal** | Stable in practice, not part of the public contract; can change in any minor release without a CHANGELOG entry | ❌ No | 🟡 Mostly — package boundaries will tighten further behind `@Internal` | `graphcompose-shared-engine-architect` skill (internal Claude / Codex artifact); [ADR-0015](../adr/0015-layered-template-architecture.md) for the canonical/engine seam | + +> **Status definitions.** *Recommended* = the path GraphCompose 2.0 will +> ship; new code targets it. *Supported* = bug fixes + behaviour-preserving +> refactors only, no new features; exists through 1.x. *Internal* = engine +> surface, not part of the public contract; can change in any minor +> release without a CHANGELOG entry. *Legacy* = bug fixes only, removed +> in 2.0; do not start new code here. + +--- + +## 2. Decision tree + +``` +I want to render a business document on GraphCompose. + +├─ Is it a CV or cover letter? +│ ├─ Yes → use a `layered` preset (cv.v2 / coverletter.v2). +│ │ See [v2-layered/using-templates.md](v2-layered/using-templates.md). +│ │ Existing `classic` (cv.presets.*) caller? Read § 3 below; the +│ │ layered preset with the same name is a drop-in replacement +│ │ for almost every case. +│ │ +│ └─ No → continue. +│ +├─ Is it an invoice or proposal? +│ └─ Use `InvoiceTemplateV2` or `ProposalTemplateV2` (the `V2` variants). +│ The `V1` variants exist for backward compatibility; do not start +│ new code on them. +│ +├─ Is it a weekly schedule? +│ └─ Use `WeeklyScheduleTemplateV1`. There is no V2 yet — the V1 API +│ will be re-shaped before 2.0 (no concrete plan yet); track in +│ the public release roadmap before adopting it long-term. +│ +└─ It's something else (custom shape, brochure, report)? + └─ Author directly on the canonical DSL: `GraphCompose.document()` + + `pageFlow(...)` or `dsl().pageFlow(...)`. Reuse `BusinessTheme` + and layered widgets (`SectionDispatcher`, `EntryCompactRenderer`, + `RichParagraphRenderer`, `CardWidget`) wherever they fit; lift + new reusable widgets into the `cv.v2/components` and + `cv.v2/widgets` packages so the next template family can share + them. +``` + +--- + +## 3. Migration table — `classic` → `layered` + +Every CV preset that shipped in `cv.presets.*` has a same-named drop-in +replacement in `cv.v2.presets.*`. Migrating a caller is the import swap +plus a theme + data-record swap (introduced below): + +```diff +-import com.demcha.compose.document.templates.cv.presets.NordicClean; ++import com.demcha.compose.document.templates.cv.v2.presets.NordicClean; + +-// before: CvSpec + BusinessTheme +-NordicClean.create(BusinessTheme.nordicClean()).render(session, cvSpec); ++// after: CvDocument + CvTheme — see the two shape changes below ++NordicClean.create(cvTheme).render(session, cvDocument); +``` + +Two real shape changes accompany the swap: + +1. **Theme.** `BusinessTheme.X()` → `CvTheme.X()`. The CV-specific + tokens (palette / typography / spacing) are split out so `cv.v2` + themes don't carry invoice / proposal vocabulary they don't use. +2. **Data record.** `CvSpec` → `CvDocument`. The data shape becomes + strongly-typed sections (`SectionGroup`, `EntryGroup`, `SkillGroup`, + …) instead of a flat `Block` permit list. The + [contributor-guide](v2-layered/contributor-guide.md) walks through + the section types end-to-end. + +### CV presets — one-to-one mapping + +| `classic` (`cv.presets.*`) | `layered` (`cv.v2.presets.*`) | Cover letter (`coverletter.v2.presets.*`) | Notes | +|---|---|---|---| +| `BlueBanner` | `BlueBanner` | `BlueBannerLetter` | | +| `BoxedSections` | `BoxedSections` | `BoxedSectionsLetter` | Reference preset for the layered architecture. | +| `CenteredHeadline` | `CenteredHeadline` | `CenteredHeadlineLetter` | Layered-only in 1.6.5+; classic version is the rebuilt one. | +| `ClassicSerif` | `ClassicSerif` | `ClassicSerifLetter` | | +| `CompactMono` | `CompactMono` | `CompactMonoLetter` | | +| `EditorialBlue` | `EditorialBlue` | `EditorialBlueLetter` | | +| `EngineeringResume` | `EngineeringResume` | `EngineeringResumeLetter` | | +| `Executive` | `Executive` | `ExecutiveLetter` | | +| `ModernProfessional` | `ModernProfessional` | `ModernProfessionalLetter` | | +| `MonogramSidebar` | `MonogramSidebar` | `MonogramSidebarLetter` | Layered version uses `pageBackgrounds(...)` for sidebar chrome (multi-page-safe). | +| `NordicClean` | `NordicClean` | `NordicCleanLetter` | Layered version ships public `NordicClean.Options`. | +| `Panel` | `Panel` | `PanelLetter` | | +| `SidebarPortrait` | `SidebarPortrait` | `SidebarPortraitLetter` | Layered version uses `pageBackgrounds(...)`. | +| `TimelineMinimal` | `TimelineMinimal` | `TimelineMinimalLetter` | | +| _(no classic)_ | `MinimalUnderlined` | _(no letter yet)_ | Layered-only. | +| _(no classic)_ | `MintEditorial` | `MintEditorialLetter` | Layered-only (shipped in v1.6.5). | + +If your caller uses a name on the left, the row tells you what to import +on the right and which cover-letter preset pairs with it. + +### Built-ins (Invoice / Proposal / WeeklySchedule) + +| V1 | V2 | Migration | +|---|---|---| +| `InvoiceTemplateV1` | `InvoiceTemplateV2` | Same data record (`InvoiceSpec`), same `BusinessTheme`. Renderer rewrite uses layered widgets; output is visually equivalent and snapshot-tested. | +| `ProposalTemplateV1` | `ProposalTemplateV2` | Same data record (`ProposalSpec`), same `BusinessTheme`. Same migration pattern as invoice. | +| `WeeklyScheduleTemplateV1` | _(no V2 yet)_ | Stay on V1 until a V2 ships. | + +### Things that are **not** in either canonical surface (still legacy) + +These live under `com.demcha.compose.v2.*`, `com.demcha.templates.*`, or +the `GraphCompose.pdf(...)` factory. They are the original (pre-1.6) +PDF-direct authoring path. They will be removed in 2.0: + +- `GraphCompose.pdf(outputFile)` and `PdfComposer`. +- `com.demcha.templates.MainPageCV`, `MainPageCvDTO`, `ModuleYml`, + `TemplateBuilder` and friends. +- `com.demcha.compose.v2.*` (engine-direct builders predating the + canonical DSL). + +If a caller still imports any of these, the migration target is +**directly the canonical DSL** (`GraphCompose.document()`) — there is no +1:1 equivalent in the template surfaces, because these classes were +never canonical templates, they were a PDF authoring shortcut. The +[migration-v1-5-to-v1-6 roadmap](../roadmaps/migration-v1-5-to-v1-6.md) +walks through the swap for the common shapes. + +--- + +## 4. Deprecation inventory — 1.x → 2.0 + +Read this when planning long-lived code or when auditing dependencies +that may already use one of the slated-for-removal types. None of these +are deleted in 1.x; the work below is anti-roadmap and lives in the +private taskboard. + +### Removed in 2.0 + +| Item | Reason | Replacement | +|---|---|---| +| `GraphCompose.pdf(...)` factory + `PdfComposer` | PDF-direct path predates the canonical DSL; bypasses layout and rendering invariants. | `GraphCompose.document(...)` + `DocumentSession.buildPdf()`. | +| `com.demcha.compose.v2.*` (the entire package) | Engine-direct builders predating canonical DSL. Mixes layout vocabulary with rendering vocabulary. | Canonical DSL surface (`document.api`, `document.dsl`, `document.node`, `document.style`). | +| `com.demcha.templates.MainPageCV`, `MainPageCvDTO`, `ModuleYml`, `TemplateBuilder` | The original CV template pre-rebuild. Replaced by `cv.presets.*` (classic) in 1.6, now slated to be replaced again by `cv.v2.*` (layered). | A `cv.v2.presets.*` preset, or direct canonical DSL authoring. | +| Entire `cv.presets.*` package (the `classic` surface) | Superseded by `cv.v2.presets.*` (layered). Every preset on the left has a same-named layered replacement (see § 3). | `cv.v2.presets.*`. | +| `DocumentSession.builder()` (deprecated alias) | Pre-rebuild builder entry point. | `GraphCompose.document()`. | +| `DocumentDsl.text(...)` (deprecated alias) | Pre-rebuild text shortcut. | `paragraph(...)` builders inside `pageFlow`. | +| `DocumentPalette.of(...)` (deprecated alias) | Pre-rebuild palette factory. | `DocumentPalette.from(...)` (or theme-specific factories). | +| PDF-specific chrome overloads on `BusinessTheme` | Coupled CV-specific tokens with PDF-specific decisions. | Layered `CvTheme` + render-time `pageBackgrounds(...)`. | + +### Open questions for 2.0 (no decision yet) + +- `WeeklyScheduleTemplateV1` — whether to ship a V2 along the layered + architecture or to deprecate weekly schedule entirely. +- `InlineRow` / `SplittableRow` / `GridNode` decisions deferred from + 1.7 — may unblock magazine-style multi-column flow without needing a + `GridNode` primitive. Tracked in the maintainers' internal release- + readiness notes; will surface here once a public 1.8 engine-refactor + roadmap is published. + +### Maven coordinates do **not** change in 2.0 + +The library `pom.xml` artifact id stays `graphcompose`; JitPack +coordinates (`com.github.DemchaAV:GraphCompose:v`) and the Maven +Central coordinates being introduced in 1.6.6 (`io.github.demchaav:graphcompose:`) +both carry through to 2.0. + +--- + +## 5. Cross-links + +- **First-class architecture references** + - [ADR-0011 Templates v2 architecture](../adr/0011-templates-v2-architecture.md) (the `classic` surface) + - [ADR-0015 Layered template architecture](../adr/0015-layered-template-architecture.md) (the `layered` surface; supersedes 0011 for new families) +- **Layered (recommended) docs** + - [README](v2-layered/README.md) · [Quickstart](v2-layered/quickstart.md) · [Using templates](v2-layered/using-templates.md) · [Authoring presets](v2-layered/authoring-presets.md) · [Contributor guide](v2-layered/contributor-guide.md) +- **Classic (supported) docs** + - [README](v1-classic/README.md) · [Authoring](v1-classic/authoring.md) +- **Migration roadmaps** + - [v1.4 → v1.5](../roadmaps/migration-v1-4-to-v1-5.md) + - [v1.5 → v1.6](../roadmaps/migration-v1-5-to-v1-6.md) + +--- + +*This page is maintained alongside the templates surfaces. When a new +preset, built-in, or deprecation lands, update §1 (status matrix) and +§3 (migration table) in the same commit. The `CanonicalSurfaceGuardTest` +documentation-coverage check enforces that no legacy API token leaks +into this doc.* diff --git a/src/test/java/com/demcha/documentation/CanonicalSurfaceGuardTest.java b/src/test/java/com/demcha/documentation/CanonicalSurfaceGuardTest.java index 20c9c6d9..6b57fb7b 100644 --- a/src/test/java/com/demcha/documentation/CanonicalSurfaceGuardTest.java +++ b/src/test/java/com/demcha/documentation/CanonicalSurfaceGuardTest.java @@ -47,7 +47,15 @@ class CanonicalSurfaceGuardTest { // Lists every retired V1 CV / cover-letter class so callers // can find the v2 replacement. Naming the legacy surface is // the explicit purpose of a migration log. - "docs/roadmaps/migration-v1-5-to-v1-6.md"); + "docs/roadmaps/migration-v1-5-to-v1-6.md", + // Decision guide for "classic vs layered template surface". + // The deprecation-inventory section names GraphCompose.pdf(...), + // PdfComposer, MainPageCV, MainPageCvDTO, ModuleYml, + // TemplateBuilder, and com.demcha.compose.v2.* / com.demcha.templates.* + // so callers can identify legacy imports in their own code and + // see the canonical-DSL replacement. Same purpose as the + // migration log above. + "docs/templates/which-template-system.md"); private static final List FORBIDDEN_PUBLIC_AUTHORING_IMPORTS = List.of( "import com.demcha.compose.engine.");