Skip to content

feat: (W-003) Legacy compatibility adapter for 3.x to 4.0 migration#2015

Open
bpamiri wants to merge 3 commits intodevelopfrom
grove/W-003-wheels-4-0-legacy-compatibility-adapter-
Open

feat: (W-003) Legacy compatibility adapter for 3.x to 4.0 migration#2015
bpamiri wants to merge 3 commits intodevelopfrom
grove/W-003-wheels-4-0-legacy-compatibility-adapter-

Conversation

@bpamiri
Copy link
Copy Markdown
Collaborator

@bpamiri bpamiri commented Apr 3, 2026

Summary

Adds the wheels-legacy-adapter package — a backward compatibility layer for smooth migration from Wheels 3.x to 4.0.

  • DeprecationLogger — 4 severity modes (silent/log/warn/error), per-request deduplication, request-scoped tracking
  • LegacyAdapter — controller-scoped shims for renderPage()renderView() and renderPageToString()renderView(returnAs="string"), plus plugin diagnostics via $legacyPluginInfo()
  • MigrationScanner — detects 7 legacy patterns with path-aware filtering (plugin patterns restricted to plugins/ directory to avoid false positives)
  • 22 TestBox BDD specs covering all three components

Migration path

  1. Stage 1: Copy package to vendor/legacyadapter — existing 3.x code works unchanged
  2. Stage 2: Run migration scanner, update code incrementally (both old and new APIs work simultaneously)
  3. Stage 3: Set mode to error to catch stragglers, then remove adapter

Also includes

  • PR workflow label config for legacyadapter package
  • CI continue-on-error for auto-label job on fork PRs

Closes #1969

Test plan

  • All 22 adapter-specific specs pass (DeprecationLogger, LegacyAdapter, MigrationScanner)
  • Full core test suite passes on Lucee 6 (H2): 2278 pass, 0 fail, 0 error
  • Full core test suite passes on Adobe CF 2025 (SQLite): 2274 pass, 0 fail, 0 error
  • CI matrix passes across all engines

🤖 Generated with Claude Code

bpamiri and others added 3 commits April 3, 2026 11:03
Backward compatibility adapter that provides:
- DeprecationLogger with configurable modes (silent/log/warn/error)
- Controller mixin shims for deprecated APIs (renderPage, renderPageToString)
- MigrationScanner that analyzes app code for legacy patterns
- Three-stage progressive migration path (install → migrate → remove)

Verified on Lucee 6 and Adobe CF 2025. Core tests pass with 0 regressions.

Closes #1969

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Remove this.version from LegacyAdapter.cfc, source version from package.json
- Add pathFilter to MigrationScanner for context-aware this.version detection
  (only flags files in plugins/ directory, avoiding false positives)
- Remove $legacyPaginationLinks shim (no migration value)
- Move test-path check from inner loop to early return for efficiency
- Update tests: add path-filter verification, update $scanContent helper
  to accept subDir parameter for simulating file locations
- Revise plan: fix mixin scope to controller, demote Plugin-to-Package
  Bridge to Plugin Diagnostics, remove phantom showErrors setting,
  remove false-premise unresolved question, reframe edge cases

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…ter tests

DirectoryCreate(path, true) is Lucee-only — Adobe CF only accepts 1 parameter.
Replace with Java File.mkdirs() which works on all CFML engines.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@github-actions github-actions bot added docs dependencies Pull requests that update a dependency file javascript Pull requests that update javascript code labels Apr 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dependencies Pull requests that update a dependency file docs javascript Pull requests that update javascript code

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Wheels 4.0: Legacy compatibility adapter and migration path Issue #1969

1 participant