# Legacy Routes Removal Checklist

Date: 2026-03-12
Scope: staged retirement of routes listed in docs/legacy-routes-inventory.md

## Global Preflight (run before each phase)

- Confirm canonical replacement routes exist and are healthy.
- Snapshot current route map:
  - `php artisan route:list --path=legacy`
  - `php artisan route:list --json > storage/logs/routes-before-phase.json`
- Capture 14-30 day usage for each candidate route from access logs / analytics.
- Define rollback rule: restore removed routes immediately if a business-critical endpoint drops or 404 volume spikes.

## Standard PR Steps (for every phase)

1. Remove targeted route entries from routes/legacy.php.
2. If needed, add explicit 301 redirects to canonical paths in routes/web.php.
3. Update route-based tests (e2e fixtures and auth guard lists).
4. Run cache clear and verify registration:
   - `php artisan optimize:clear`
   - `php artisan route:list --json`
5. Add release note entry with removed paths and replacements.

## SEO Safety Checklist

- Ensure removed indexed URLs either:
  - return 301 to final canonical URL, or
  - return 410 only when intentional and approved.
- Keep canonical tags correct on destination pages.
- Re-submit updated sitemap if route removals change indexed URLs.
- Monitor Search Console coverage and soft-404 reports for 2-4 weeks.

## Monitoring Checklist (post-deploy)

- Track 404 count by path prefix for removed routes.
- Track 301 volume for newly redirected legacy paths.
- Watch top entry pages for traffic drops.
- Verify no auth redirect loops were introduced on legacy auth-only pages.

## Phase-by-Phase Execution

### Phase 1: Redirect-only endpoints (lowest risk)

Targets:
- /top-authors
- /interviews
- /apply
- /bug-report
- /browse-redirect
- /wallpapers-redirect

Phase checks:
- Confirm each path still has a valid replacement target.
- Validate 301 status and location header for each route.

### Phase 2: Alias pair cleanup

Targets:
- /featured vs /featured-artworks
- /uploads/latest vs /latest
- /comments/latest vs /latest-comments
- /downloads/today vs /today-downloads
- /comments/monthly vs /monthly-commentators

Phase checks:
- Pick one canonical URL per pair.
- Keep redirects from removed alias to chosen canonical.
- Update internal links to canonical only.

### Phase 3: Controller-backed legacy pages

Targets:
- /browse
- /category/{group}/{slug?}/{id?}
- /browse-categories
- /daily-uploads
- /members
- /members/photos
- /authors/top
- /top-favourites
- /today-in-history
- /chat
- /chat_post
- /favourites/{id?}/{username?}
- /favourites/{userId}/delete/{artworkId}
- /gallery/{id}/{username?}

Phase checks:
- Confirm parity exists in modern endpoints before removal.
- Add temporary 301 map for any high-traffic paths.
- Validate auth and CSRF behavior for migrated POST endpoints.

### Phase 4: Profile URL legacy surface

Targets:
- /user/{username}
- /profile/{id}/{username?}
- /profile/{username}
- /user

Phase checks:
- Validate deterministic mapping to /@username.
- Handle missing username and renamed accounts gracefully.
- Verify no duplicate-content issues remain after redirects.

### Phase 5: RSS compatibility endpoints (communication required)

Targets:
- /rss/latest-uploads.xml
- /rss/latest-skins.xml
- /rss/latest-wallpapers.xml
- /rss/latest-photos.xml

Phase checks:
- Identify external consumers (feed readers, partner integrations).
- Publish migration notice before retirement.
- Keep stable replacement feed URLs live before cutover.

## Fast QA Matrix

Test each removed or redirected route for:
- Anonymous user request
- Authenticated user request
- Expected status code (301/200/404/410)
- Correct final destination URL
- No infinite redirect chain

Suggested command:
- `php artisan test --filter=routes`

## Rollback Playbook

- Reintroduce removed route definitions from git history.
- Clear caches: `php artisan optimize:clear`.
- Redeploy hotfix.
- Re-run route smoke tests and check access logs.