64 lines
3.7 KiB
Markdown
64 lines
3.7 KiB
Markdown
# Research: Filament v5.2.1 Upgrade
|
||
|
||
**Feature**: 102-filament-5-2-1-upgrade
|
||
**Date**: 2026-02-20
|
||
|
||
## Upstream Notes (v5.2.0 → v5.2.1)
|
||
|
||
Source: Filament GitHub releases (`v5.2.0...v5.2.1`). Highlights relevant to this repo’s verification gates:
|
||
|
||
- Tenancy: **"Don't register tenancy on models when it is not active"**
|
||
- Risk: Multi-panel apps may previously have had unintended tenant scoping or auto-association in a non-tenant panel.
|
||
- Verification mapping: staging smoke must include both `/admin` and `/system` panels and check for unexpected tenant filtering or missing tenant association.
|
||
|
||
- Tables: **"bulk action receives non-selectable records when using \"Select all\""**
|
||
- Risk: bulk actions can behave incorrectly when tables use non-selectable rows.
|
||
- Verification mapping: smoke includes select-all + non-selectable-row scenarios.
|
||
|
||
- Testing: **"Fix assertHasTableActionErrors() deprecated replacement"**
|
||
- Risk: tests relying on deprecated assertion guidance may need to follow the corrected replacement pattern.
|
||
- Verification mapping: full suite must be green; treat any new deprecation warnings or assertion failures as regressions to address.
|
||
|
||
## Decisions
|
||
|
||
### Decision: Upgrade Filament constraint to `^5.2.1`
|
||
|
||
- Rationale:
|
||
- Patch-level stability/bugfix upgrade with known fixes relevant to this app (tenancy registration behavior; table bulk selection; testing assertions).
|
||
- Keeps us current within Filament v5 and reduces upgrade debt.
|
||
- Alternatives considered:
|
||
- Stay on `^5.0` until a larger upgrade window is available (rejected: leaves known upstream fixes unconsumed).
|
||
|
||
### Decision: Allow plugin/extension dependency bumps (Composer-only) in the same PR
|
||
|
||
- Rationale:
|
||
- Patch upgrades can be blocked by transitive constraints; allowing composer-only plugin bumps preserves the “dependency-only” scope.
|
||
- Avoids splitting into multiple PRs that each touch `composer.lock` while still preventing application code changes.
|
||
- Alternatives considered:
|
||
- Strict Filament-only bump; abort on plugin incompatibility (rejected: increases likelihood of blocking the upgrade).
|
||
- Allow minimal application code compatibility fixes (rejected: conflicts with “no feature changes” scope).
|
||
|
||
### Decision: Verification gates
|
||
|
||
- Automated gate (required): **Full automated regression suite + frontend build**
|
||
- Rationale: ensures both PHP/Livewire/Filament and frontend asset pipeline remain stable.
|
||
- Alternatives considered: tests-only (rejected: build failures often surface asset regressions).
|
||
|
||
- Manual gate (required): **Staging UI smoke** for Admin (`/admin`) and System (`/system`, if present)
|
||
- Rationale: catches runtime regressions that can slip past tests (modals, table selection, tenancy-related UI behavior).
|
||
- Alternatives considered: local-only smoke (rejected: staging is closer to production and aligns with rollback criteria).
|
||
|
||
### Decision: Rollback strategy
|
||
|
||
- Rationale:
|
||
- Fastest safe rollback is to revert `composer.lock` (and the Filament constraint if changed) and redeploy the last known-good artifact.
|
||
- Alternatives considered:
|
||
- “Forward fix” under pressure (rejected: increases outage window and risk).
|
||
|
||
## Implementation Outcome Notes (2026-02-20)
|
||
|
||
- Filament was upgraded to `v5.2.1` successfully.
|
||
- No additional Filament plugin/extension constraints were required in `composer.json` (no plugin bumps).
|
||
- Composer resolution included transitive framework updates (not plugin-specific), including Laravel `v12.52.0` and Livewire `v4.1.4`.
|
||
- During verification, a tenant-scope regression surfaced in backup-set listing tests after the upgrade; mitigation was applied by explicitly scoping `BackupSetResource` queries to the active tenant.
|