# Upgrade Notes — v8.1.1 to v9.0.0

## Before upgrading

- Use staging first.
- Back up the database and `wp-content`.
- Record the currently active theme/plugin versions.
- Export the Area directory if it contains live edits.
- Capture screenshots of the current navigation, homepage Customizer values and any custom menus.

## What the automatic v9 migration changes

- Creates missing strategic pages.
- Keeps existing non-empty page content.
- Sets the Home page as the static front page and sets News as the posts page only when a posts page is not already assigned.
- Adds `bible` and `safeguarding` to existing Homepage Builder configurations if missing.
- Seeds only missing strategic content items.
- Reorganises the Primary Menu automatically only when it still exactly matches the historical untouched starter menu. Custom editorial menus are preserved.
- Synchronises v9 role/capability definitions.
- Refreshes rewrite rules once for the new singular custom-content URLs.

## Review after upgrading

1. **Appearance → Customize** — logo, hero, contacts, social links, impact figures and CTA links.
2. **SU Nigeria → Homepage Builder** — order and visibility.
3. **Regions / Areas** — formation scope and contact accuracy.
4. **Events** — correct dates, venues and choose the approved registration mode: details only, native website registration, or external registration link.
5. **Resources** — file/external URLs and resource types.
6. **Media Library (SU content type)** — Region/Area and internal media-consent references.
7. **Users** — Regional/Area assignments and least-privilege access.
8. **Safeguarding / Privacy** — authorised policy review.
9. **Give / Partner** — Finance-approved links/details only.
10. **Search & Discoverability** — official verification values when available.

## URL changes

The old package could allow page/archive rewrite collisions. v9 intentionally separates curated landing pages from individual records:

- `/events/` → events landing page
- `/event/example-event/` → event detail
- `/resources/` → resource centre
- `/resource/example-resource/` → resource detail
- `/ministries/` → ministries landing page
- `/ministry/example-ministry/` → ministry detail
- `/donate/` → giving/partnership landing page
- `/giving/example-campaign/` → campaign detail
- `/regions-areas/` → formation finder/directory
- `/region/example-region/` and `/area/example-area/` → formation detail

If the staging site has externally indexed old custom-record URLs, create 301 redirects before production cutover.

## Rollback

If a staging test fails, restore the pre-upgrade files and database backup together. Do not roll back only the plugin files after content/capability migrations without restoring the matching database state.

## Registration data migration

The v9 code uses `wp_su_event_registrations` (with the site database prefix in place of `wp_`) as the canonical native event-registration table. If an older `sunigeria_event_registrations` table exists and the canonical table is empty, v9 can copy historical records once so the new Registrations and Event Analytics screens remain consistent. Verify counts on staging before production cutover.

## App/API authentication migration

New app logins receive expiring v9 bearer tokens. Existing pre-v9 tokens receive a short transitional expiry when first used under v9. Test any approved mobile/client integrations on staging, then encourage re-login so clients receive the new token format.