Skip to content

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

Merged
bpamiri merged 3 commits into
developfrom
grove/W-003-wheels-4-0-legacy-compatibility-adapter-
Apr 8, 2026
Merged

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

Conversation

@bpamiri

@bpamiri bpamiri commented Apr 3, 2026

Copy link
Copy Markdown
Collaborator

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
@bpamiri @claude
feat: (W-003) add wheels-legacy-adapter package for 3.x to 4.0 migration
9a017ea 
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>
@bpamiri @claude
fix: (W-003) address reviewer feedback on legacy adapter
b472bef 
- 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>
@bpamiri @claude
fix: (W-003) use Java mkdirs() for cross-engine compatibility in adap…
c1bc783 
…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
@bpamiri
bpamiri merged commit 180c8bb into develop Apr 8, 2026
3 checks passed
@bpamiri
bpamiri deleted the grove/W-003-wheels-4-0-legacy-compatibility-adapter- branch April 8, 2026 12:03
bpamiri added a commit that referenced this pull request Apr 16, 2026
@bpamiri @claude
docs: add Wheels 4.0 upgrade guide
e8cd1db 
New standalone upgrade guide at docs/src/introduction/upgrading-to-4.0.md
covering the 10 Breaking changes in 4.0 plus migration paths:

  - Before you start (backup, test environment, CHANGELOG)
  - 5-minute upgrade checklist (scannable table)
  - Breaking changes — detailed:
    * 6 security-hardening default flips (CORS, env-switch, HSTS,
      CSRF SameSite, RateLimiter trustProxy, RateLimiter proxy
      strategy)
    * 1 CLI rename (wheels snippets → wheels code)
    * 3 namespace / directory renames (wheels.Test → WheelsTest,
      tests/specs/functions/ → functional/, application.wirebox →
      application.wheelsdi)
  - Legacy Compatibility Adapter (#2015) — soft landing
  - Recommended (not required) migrations — 10 items
  - Still stuck? — links to audit, comparison, adapter, discussions

Each Breaking item uses a consistent 4-part format:
  What changed / How to detect / How to fix / Opt-out

Plus a one-line callout added to the top of the existing
docs/src/introduction/upgrading.md linking to the new guide.

Companion to:
  #2123 — 4.0 feature audit
  #2124 — CHANGELOG Unreleased expansion
  #2125 — 3.0 → 4.0 comparison doc

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@bpamiri bpamiri mentioned this pull request Apr 16, 2026
Merged
5 of 7 tasks
bpamiri added a commit that referenced this pull request Apr 16, 2026
@bpamiri @claude
docs: add Wheels 4.0 upgrade guide
2cd53cb 
New standalone upgrade guide at docs/src/introduction/upgrading-to-4.0.md
covering the 10 Breaking changes in 4.0 plus migration paths:

  - Before you start (backup, test environment, CHANGELOG)
  - 5-minute upgrade checklist (scannable table)
  - Breaking changes — detailed:
    * 6 security-hardening default flips (CORS, env-switch, HSTS,
      CSRF SameSite, RateLimiter trustProxy, RateLimiter proxy
      strategy)
    * 1 CLI rename (wheels snippets → wheels code)
    * 3 namespace / directory renames (wheels.Test → WheelsTest,
      tests/specs/functions/ → functional/, application.wirebox →
      application.wheelsdi)
  - Legacy Compatibility Adapter (#2015) — soft landing
  - Recommended (not required) migrations — 10 items
  - Still stuck? — links to audit, comparison, adapter, discussions

Each Breaking item uses a consistent 4-part format:
  What changed / How to detect / How to fix / Opt-out

Plus a one-line callout added to the top of the existing
docs/src/introduction/upgrading.md linking to the new guide.

Companion to:
  #2123 — 4.0 feature audit
  #2124 — CHANGELOG Unreleased expansion
  #2125 — 3.0 → 4.0 comparison doc

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
bpamiri added a commit that referenced this pull request Apr 16, 2026
@bpamiri @claude
docs: add Wheels 4.0 upgrade guide
eab6da1 
New standalone upgrade guide at docs/src/introduction/upgrading-to-4.0.md
covering the 10 Breaking changes in 4.0 plus migration paths:

  - Before you start (backup, test environment, CHANGELOG)
  - 5-minute upgrade checklist (scannable table)
  - Breaking changes — detailed:
    * 6 security-hardening default flips (CORS, env-switch, HSTS,
      CSRF SameSite, RateLimiter trustProxy, RateLimiter proxy
      strategy)
    * 1 CLI rename (wheels snippets → wheels code)
    * 3 namespace / directory renames (wheels.Test → WheelsTest,
      tests/specs/functions/ → functional/, application.wirebox →
      application.wheelsdi)
  - Legacy Compatibility Adapter (#2015) — soft landing
  - Recommended (not required) migrations — 10 items
  - Still stuck? — links to audit, comparison, adapter, discussions

Each Breaking item uses a consistent 4-part format:
  What changed / How to detect / How to fix / Opt-out

Plus a one-line callout added to the top of the existing
docs/src/introduction/upgrading.md linking to the new guide.

Companion to:
  #2123 — 4.0 feature audit
  #2124 — CHANGELOG Unreleased expansion
  #2125 — 3.0 → 4.0 comparison doc

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
bpamiri added a commit that referenced this pull request Apr 16, 2026
@bpamiri @claude
docs: add Wheels 4.0 upgrade guide (#2130)
0cbadb8 
* docs: spec for Wheels 4.0 upgrade guide

Design doc for a new standalone upgrade guide at
docs/src/introduction/upgrading-to-4.0.md. Scope:

- Breaking + migration path (~350 lines)
- 10 Breaking items covered with consistent 4-part format:
  what changed / how to detect / how to fix / opt-out
- Legacy Compatibility Adapter documented as soft-landing option
- Recommended (not required) migrations section
- Single callout link added to existing upgrading.md

Spec companion to the feature audit (#2123), 3.0 → 4.0 comparison
(#2125), and CHANGELOG catch-up (#2124), which together form the
4.0 release-documentation stack.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: implementation plan for Wheels 4.0 upgrade guide

12-task plan covering:
  - File scaffold (front-matter + H1)
  - Before-you-start + 5-minute checklist
  - 10 Breaking items (3 tasks grouped by theme)
  - Legacy Compatibility Adapter section
  - Recommended migrations section
  - Still-stuck section
  - Callout link added to upgrading.md
  - Link integrity audit
  - Commit + push + PR

Each task includes the actual prose/code to write, with
verification via grep / wc / link-integrity script. No
placeholders; plan is executable end-to-end.

Companion to:
  docs/superpowers/specs/2026-04-16-wheels-4.0-upgrade-guide-design.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: add Wheels 4.0 upgrade guide

New standalone upgrade guide at docs/src/introduction/upgrading-to-4.0.md
covering the 10 Breaking changes in 4.0 plus migration paths:

  - Before you start (backup, test environment, CHANGELOG)
  - 5-minute upgrade checklist (scannable table)
  - Breaking changes — detailed:
    * 6 security-hardening default flips (CORS, env-switch, HSTS,
      CSRF SameSite, RateLimiter trustProxy, RateLimiter proxy
      strategy)
    * 1 CLI rename (wheels snippets → wheels code)
    * 3 namespace / directory renames (wheels.Test → WheelsTest,
      tests/specs/functions/ → functional/, application.wirebox →
      application.wheelsdi)
  - Legacy Compatibility Adapter (#2015) — soft landing
  - Recommended (not required) migrations — 10 items
  - Still stuck? — links to audit, comparison, adapter, discussions

Each Breaking item uses a consistent 4-part format:
  What changed / How to detect / How to fix / Opt-out

Plus a one-line callout added to the top of the existing
docs/src/introduction/upgrading.md linking to the new guide.

Companion to:
  #2123 — 4.0 feature audit
  #2124 — CHANGELOG Unreleased expansion
  #2125 — 3.0 → 4.0 comparison doc

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This was referenced May 12, 2026
Merged
Merged
Merged
Merged
Merged
Merged
Merged
Merged
Merged
This was referenced May 21, 2026
Merged
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

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

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

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

1 participant

@bpamiri