chore(engine): deprecate the legacy ECS PDF renderer (F11 follow-up)#150
Merged
Conversation
Follow-up to F11/PR #148, which deprecated the engine.core/layout/pagination ECS packages. engine.render.pdf is a canonical-mixed package -- it also holds the canonical-shared PdfFont, GlyphFallbackLogger, and the header/footer + watermark renderers used by document.backend.fixed.pdf -- so the legacy Entity-based PDF renderer could not be marked @deprecated at package level without dragging those along. Physically split it: move the dead ECS renderer (PdfRenderingSystemECS plus PdfRenderSession/PdfCanvas/PdfStream/PdfImageCache/PdfFileManagerSystem/PdfGuidesRenderer, the 13 render-marker handlers, and the TableCellBox/PdfBookmarkBuilder helpers) into a new engine.render.pdf.ecs with .handlers/.helpers sub-packages, then mark those three packages @deprecated at package level (no deprecation-warning cascade, same pattern as F11). The four canonical-shared types stay in engine.render.pdf; colocated tests move with the package-private classes. The relocated renderer has no public entry point (canonical PDF output goes through document.backend.fixed.pdf) and carries no binary-compatibility promise, so the package move is excluded from the japicmp gate rather than treated as a breaking removal. Package docs (engine.render.pdf, package-map, implementation-guide) updated to reflect the canonical/legacy split. No behaviour change; verify -P japicmp green (1152 tests + guards + japicmp).
Follow-up to the legacy ECS PDF renderer split: CONTRIBUTING.md and docs/architecture/overview.md still pointed at the vacated engine.render.pdf.handlers / .helpers locations, and CONTRIBUTING + implementation-guide had broken links to the moved PdfRenderingSystemECSDispatchTest and TableCellBox. Repath to engine.render.pdf.ecs.* and frame the ECS renderer guidance as legacy (canonical PDF output is document.backend.fixed.pdf). Doc-only; guard suite (DocumentationCoverageTest, CanonicalSurfaceGuardTest, DocumentationExamplesTest, PDF boundary guards) green. Surfaced by an independent review of the package-split PR.
…-ecs-pdf-render # Conflicts: # CHANGELOG.md # pom.xml
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.
Follow-up to #148 (F11), which deprecated the
engine.core/engine.layout/engine.paginationECS packages. This continues the ECS phase-out into the PDF render pipeline.Why a package split (not class-level
@Deprecated)engine.render.pdfis a canonical-mixed package: alongside the legacy renderer it holds the canonical-sharedPdfFont,GlyphFallbackLogger, and the header/footer + watermark renderers thatdocument.backend.fixed.pdfdepends on. A package-level@Deprecated(F11's no-cascade pattern) wasn't possible without dragging those along, and class-level@Deprecatedwould cascade deprecation warnings across the legacy engine and the 64-file test harness.Investigation also corrected the original framing: the
handlers/subpackage (all 13, typedRenderHandler<…, PdfRenderingSystemECS>) andhelpers/TableCellBox+helpers/PdfBookmarkBuilderare legacy ECS too, not canonical — the canonical pipeline uses its owndocument.backend.fixed.pdf.handlers.*. The genuinely canonical-shared set is only 4 classes.What moved
Into new
@Deprecatedpackagesengine.render.pdf.ecs/.handlers/.helpers:PdfRenderingSystemECS,PdfRenderSession,PdfCanvas,PdfStream,PdfImageCache,PdfFileManagerSystem,PdfGuidesRendererTableCellBox,PdfBookmarkBuilderLeft in
engine.render.pdf(canonical-shared, not deprecated):PdfFont,GlyphFallbackLogger,helpers/PdfHeaderFooterRenderer,helpers/PdfWatermarkRenderer.Binary compatibility
The relocated renderer has no public entry point (canonical PDF output goes through
document.backend.fixed.pdf) and carries no binary-compatibility promise, so the move is excluded from the japicmp gate — relocated.ecs*packages + vacated original FQNs — rather than treated as a breaking removal, the same rationale as the existingdocument.layout.payloadsexclude.Verification
./mvnw -B -ntp verify -pl . -P japicmpgreen: 1152 tests, 0 failures/errors/skipped, guards + japicmp pass. Pure mechanical move (zero non-import content changes in the moved files); canonicaldocument.*untouched. Package docs (engine.render.pdfpackage-info,package-map.md,implementation-guide.md) updated to reflect the canonical/legacy split.