124 lines
4.1 KiB
Markdown
124 lines
4.1 KiB
Markdown
# Implementation Plan: Filament v5.2.1 Upgrade
|
||
|
||
**Branch**: `feat/102-filament-5-2-1-upgrade` | **Date**: 2026-02-20 | **Spec**: `specs/102-filament-5-2-1-upgrade/spec.md`
|
||
**Input**: Feature specification from `/specs/102-filament-5-2-1-upgrade/spec.md`
|
||
|
||
## Summary
|
||
|
||
Upgrade Filament to v5.2.1 (or newer within 5.2.x) as a **dependency-only** change.
|
||
|
||
Verification gates (per spec clarifications):
|
||
|
||
- Automated: full test suite + frontend build
|
||
- Manual: staging UI smoke (Admin `/admin/*` + System `/system/*` if present)
|
||
|
||
No application feature work, no schema changes, and no new Graph calls are in scope.
|
||
|
||
## Technical Context
|
||
|
||
**Language/Version**: PHP 8.4.x (runtime), Composer constraint `php: ^8.2`
|
||
**Primary Dependencies**: Laravel 12, Filament 5, Livewire 4
|
||
**Storage**: PostgreSQL (Sail), plus filesystem storage for logs/cache
|
||
**Testing**: Pest (via `artisan test`)
|
||
**Target Platform**: Web application (Sail locally; Dokploy containers in staging/prod)
|
||
**Project Type**: web
|
||
**Performance Goals**: N/A (dependency-only patch upgrade)
|
||
**Constraints**:
|
||
|
||
- Dependency-only changes (Composer-only). No application code changes for compatibility.
|
||
- Test-only changes in `tests/**` are allowed if needed to keep the suite green; no runtime behavior changes.
|
||
- No new panels/routes/resources. No UX/IA changes intended.
|
||
- Verification must include `/admin` and `/system` (if System panel exists).
|
||
- Staging smoke is mandatory.
|
||
|
||
**Scale/Scope**: N/A for this change; treat any behavior delta as regression unless it’s a documented upstream bugfix we accept.
|
||
|
||
## Constitution Check
|
||
|
||
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
||
|
||
Result: **PASS**
|
||
|
||
- No new Microsoft Graph calls are introduced.
|
||
- No new write/change flows, jobs, or `OperationRun` patterns are introduced.
|
||
- No RBAC model changes are introduced; `/admin` and `/system` planes remain separated.
|
||
- No new or modified Filament Resources/Pages/RelationManagers are introduced (dependency-only upgrade).
|
||
|
||
## Project Structure
|
||
|
||
### Documentation (this feature)
|
||
|
||
```text
|
||
specs/102-filament-5-2-1-upgrade/
|
||
├── spec.md
|
||
├── plan.md
|
||
├── research.md
|
||
├── data-model.md
|
||
├── quickstart.md
|
||
└── contracts/
|
||
└── README.md
|
||
```
|
||
|
||
### Source Code (repository root)
|
||
|
||
```text
|
||
app/
|
||
bootstrap/
|
||
config/
|
||
resources/
|
||
routes/
|
||
tests/
|
||
```
|
||
|
||
**Structure Decision**: Single Laravel web application (Filament panels live under `app/Filament/**`).
|
||
|
||
## Phase 0 — Outline & Research
|
||
|
||
Goal: confirm upgrade target, identify upstream behavior changes, and map them to verification.
|
||
|
||
Deliverable:
|
||
|
||
- `research.md` capturing decisions + rationale + alternatives (completed)
|
||
|
||
Key research topics:
|
||
|
||
- Filament v5.2.0 → v5.2.1 release notes:
|
||
- tenancy registration behavior when tenancy is not active
|
||
- bulk “Select all” excluding non-selectable records
|
||
- corrected guidance around testing assertion replacement
|
||
|
||
## Phase 1 — Design & Contracts
|
||
|
||
This is a dependency-only upgrade; design outputs focus on explicitly stating “no contract changes” and providing a verification/rollback runbook.
|
||
|
||
Deliverables:
|
||
|
||
- `data-model.md` (completed; explicitly no schema/entity changes)
|
||
- `contracts/README.md` (completed; explicitly no API/Graph contract changes)
|
||
- `quickstart.md` (completed; verification + rollback runbook)
|
||
|
||
Agent context update (required):
|
||
|
||
- Run `.specify/scripts/bash/update-agent-context.sh copilot` after Phase 1 outputs exist.
|
||
|
||
Post-design constitution re-check:
|
||
|
||
- Still **PASS** (no new app code introduced).
|
||
|
||
## Phase 2 — Implementation Task Planning (for /speckit.tasks)
|
||
|
||
Planned task breakdown (to be materialized into `tasks.md` via `/speckit.tasks`):
|
||
|
||
1. Composer upgrade tasks
|
||
- Bump `filament/filament` constraint to `^5.2.1`
|
||
- Resolve plugin constraints (Composer-only)
|
||
- Run `php artisan filament:upgrade` if required by Filament upgrade guidance
|
||
2. Verification tasks (automated)
|
||
- Run `vendor/bin/sail artisan test --compact`
|
||
- Run `vendor/bin/sail npm run build`
|
||
3. Verification tasks (manual)
|
||
- Staging deploy
|
||
- Staging UI smoke (Admin + System panels)
|
||
4. Rollback tasks
|
||
- Document exact rollback steps in PR description (linked to `quickstart.md`)
|