ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
fix/pest-makeassignment-collision
TenantAtlas/specs/102-filament-5-2-1-upgrade/spec.md
ahmido 8f8bc24d1d feat: upgrade Filament to v5.2.1 (#124) 
What: Upgrade Filament auf v5.2.1 (inkl. composer.lock + veröffentlichte Filament assets unter public), SpecKit-Doku unter specs/102-..., plus kleine Anpassungen in Tests + Tenant-Scoping in BackupSetResource.
Verification: vendor/bin/sail bin pint --dirty --format agent (pass) + vendor/bin/sail artisan test --compact [AlertDeliveryViewerTest.php](http://_vscodecontentref_/6) tests/Feature/Filament/BackupSetGraphSafetyTest.php (pass)
Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #124
2026-02-20 12:20:42 +00:00

8.6 KiB
Raw Permalink Blame History

Feature Specification: Filament v5.2.1 Upgrade

Feature Branch: feat/102-filament-5-2-1-upgrade
Created: 2026-02-20
Status: Draft
Input: User description: "Upgrade the Filament admin panel framework to v5.2.1 (patch-level), with enterprise-grade verification and no feature changes."

Spec Scope Fields (mandatory)

  • Scope: workspace
  • Primary Routes: Filament panels: Admin (/admin/*) and System (/system/*, if present)
  • Data Ownership: No data model or schema changes are intended (dependency-only change)
  • RBAC: No changes intended; existing membership + capability enforcement remains the source of truth

Clarifications

Session 2026-02-20

  • Q: Which Filament panel(s) are in the verification gate (smoke + no runtime errors)? → A: Admin + System panels (/admin/* and /system/*, if the System panel exists).
  • Q: How should plugin incompatibilities be handled during the upgrade? → A: Allow plugin version bumps in the same PR, but no application code changes (composer-only).
  • Q: Where must the UI smoke be executed for the verification gate? → A: Staging UI smoke is required (local smoke is optional/early).
  • Q: What must the automated verification gate include beyond the test suite? → A: Full automated regression suite + frontend build.

Assumptions

  • The current mainline build is green (automated regression suite passing) before the upgrade is applied.
  • The application already meets the upstream framework requirements for Filament v5 (this change is patch-level, not a major migration).
  • No UI/IA changes are intended; any observed behavior change during verification is treated as a regression.
  • If the automated regression suite fails due to upstream test assertion/deprecation changes, test-only updates under tests/** are allowed to restore a green baseline; runtime application code remains unchanged.

Dependencies

  • All currently installed Filament extensions/plugins used by the application are compatible with v5.2.1.
  • If compatibility requires it, Filament plugin/extension packages MAY be upgraded in the same PR as part of this dependency-only change, provided no application code changes are required.

User Scenarios & Testing (mandatory)

User Story 1 - Ship the patch upgrade safely (Priority: P1)

As a platform engineer, I want the admin UI framework upgraded to v5.2.1 so that we pick up upstream stability and bug fixes without changing product behavior.

Why this priority: This unblocks maintenance, reduces risk of known upstream issues, and keeps upgrade debt low.

Independent Test: The change is successful if the automated regression suite is green and the application boots into the admin panel(s) without runtime errors.

Acceptance Scenarios:

  1. Given the current mainline build is passing automated verification, When the upgrade is applied, Then the automated regression suite remains fully passing.
  2. Given the upgrade is applied, When an authenticated admin user opens the Admin panel landing page and (if present) the System panel landing page, Then each page renders without errors and navigation is usable.

User Story 2 - Validate core admin workflows (Priority: P2)

As an operator/QA, I want a short, repeatable UI smoke to confirm that the most critical admin workflows still work after the upgrade.

Why this priority: Patch upgrades can regress tables/actions/modals; a fast smoke test catches high-impact breakage early.

Independent Test: A human can complete the smoke checklist in 5–10 minutes without encountering a blocking error.

Acceptance Scenarios:

  1. Given an authenticated user in the Admin panel and (if present) the System panel, When they navigate between key sections, Then navigation loads each page without errors.
  2. Given a list/table view, When the user selects multiple rows and uses bulk actions (including “select all”), Then selections and bulk actions behave correctly and do not affect non-selectable rows.
  3. Given create/edit flows, When the user opens and confirms modals (including destructive confirmations), Then modals display and complete without runtime errors.

User Story 3 - Roll back confidently if needed (Priority: P3)

As a platform engineer, I want a clear rollback so that any unexpected regression can be reversed quickly.

Why this priority: Dependency upgrades can have transitive compatibility issues; rollback is the safety net.

Independent Test: Rollback instructions are complete enough that another engineer can restore the previous known-good dependency set.

Acceptance Scenarios:

  1. Given a regression is found during verification, When rollback steps are executed, Then the previous dependency set is restored and verification returns to green.

Edge Cases

  • Extension/plugin compatibility breaks at runtime (boot failures, missing classes, broken UI components).
  • Composer-level plugin constraints block resolution to Filament v5.2.1 without bumping one or more plugin versions.
  • Tenancy-related behavior changes (e.g., tenancy not being active where expected, or tenancy being registered when it should not be).
  • Table selection edge cases (select-all, mixed selectable/non-selectable rows) behave inconsistently.
  • Automated regression suite is green but UI smoke finds a blocking runtime error (e.g., modal/action rendering).

Requirements (mandatory)

Constitution alignment (required): This change MUST NOT introduce any new Microsoft Graph calls, new write/change behaviors, or new long-running/queued/scheduled work.

Constitution alignment (RBAC-UX): No authorization model changes are intended. Any discovered RBAC behavior changes during verification MUST be treated as a regression and resolved before shipping.

Constitution alignment (Filament Action Surfaces): No Filament Resource / RelationManager / Page behavior is intended to change. If any action surface behavior changes as a side effect of the upgrade, it MUST be documented and explicitly verified as non-regressive.

Functional Requirements

  • FR-001: The system MUST upgrade Filament to version 5.2.1 or newer within the 5.2.x patch line.
  • FR-002: The system MUST preserve existing admin panel behavior (no intentional user-facing feature changes).
  • FR-003: The system MUST remain compatible with all currently installed Filament extensions/plugins used by the application.
  • FR-004: The system MUST pass the full automated regression suite after the upgrade.
  • FR-005: The system MUST pass the defined UI smoke checklist without blocking errors.
  • FR-006: The system MUST provide a documented rollback procedure that restores the previous dependency set.
  • FR-007: The upgrade MUST include a review of upstream release notes from 5.2.0 → 5.2.1, with any relevant behavioral changes mapped to verification steps.
  • FR-008: The verification gate MUST include both the Admin panel and (if present) the System panel.
  • FR-009: If plugin/extension dependency upgrades are required to achieve Filament v5.2.1 compatibility, they MUST be limited to dependency changes (no application code changes).
  • FR-010: The UI smoke verification MUST be executed on staging as part of the go/no-go gate (local smoke is optional/early signal).
  • FR-011: The automated verification gate MUST include the full automated regression suite and a successful frontend build.

UI Action Matrix (mandatory when Filament is changed)

This is a dependency-only upgrade. No specific action surfaces are intentionally added or modified.

Surface Location Header Actions Inspect Affordance (List/Table) Row Actions (max 2 visible) Bulk Actions (grouped) Empty-State CTA(s) View Header Actions Create/Edit Save+Cancel Audit log? Notes / Exemptions
Dependency upgrade only N/A N/A N/A N/A N/A N/A N/A N/A N/A Verify existing surfaces via smoke checklist and regression suite.

Success Criteria (mandatory)

Measurable Outcomes

  • SC-001: 100% of the automated regression suite passes on the upgrade branch.
  • SC-002: The UI smoke checklist can be completed on staging in ≤ 10 minutes with 0 blocking errors.
  • SC-003: No new “critical” regressions are introduced in admin workflows (0 release-blocking issues found during verification).
  • SC-004: Rollback to the previous dependency set can be executed in ≤ 15 minutes on staging (measured from decision-to-rollback to green verification).
  • SC-005: The frontend build completes successfully on the upgrade branch.