chapter-organizer/docs/instructions/year-rollover.md

# Year Rollover Runbook

**Created:** 2026-08-14  
**Last updated:** 2026-08-28  
**Description:** How to roll the chapter into a new competition year using the locked New Year wizard.

## Prerequisites

1. Confirm **School Level** is set correctly on [Chapter Settings](/settings/chapter) (`Middle School` or `High School`). That drives the graduating grade (8 or 12).
2. Have the list of **returning students** and the **new officer slate** ready.
3. Plan a short maintenance window: after apply you must **restart the app** so printouts pick up the new competition year.
4. On Docker, confirm the data volume is `./data:/app/Data` (capital **D**). See `DEPLOYMENT.md` — otherwise the automatic backup may not land on the host.

## Steps

1. Sign in as an **Administrator**.
2. Open **New Year Rollover** at `/settings/new-year` (Admin nav: “New Year Rollover (locked)”).
3. **Unlock the wizard** (required every session):
   - Check both acknowledgment boxes.
   - Type `ROLLOVER` and click **Unlock wizard**.
   - Refreshing or using **Lock again** re-locks it.
4. **Step 1 — Year & grades**
   - Confirm the target competition year (defaults to current + 1).
   - Confirm the chapter type / graduating grade shown from Chapter Settings.
5. **Step 2 — Returning roster**
   - Uncheck anyone who is not returning (grade at/above graduating is unchecked by default).
   - Optionally paste a name list (`Last, First` or `First Last`) and click **Apply pasted names**.
6. **Step 3 — Officers**
   - Assign each office from returning students, or leave vacant.
   - Officers who are brand-new students can be set later on the student edit page.
7. **Step 4 — Season reset**
   - Teams, event rankings, and meeting history are always cleared.
   - Leave **Clear all event occurrences** checked unless you have a reason to keep last year's calendar rows.
8. **Step 5 — Preview & apply**
   - Review promotions, removals, officers, and warnings.
   - Type the target competition year exactly to enable **Apply rollover**.
   - Confirm the destructive dialog. The wizard creates `Data/backups/pre-rollover-yyyyMMdd-HHmmss.db` first; that file is the only undo.
9. **Restart the application** so the home page and printouts show the new competition year.
10. **Add new students** via `/students/create` or `/import`.
    - `/import` is add-only and skips existing first+last name matches, so re-importing a full roster is safe for returners.
11. **Import the new state schedule** from the calendar import page.
12. On **Meeting Schedule**, click **Reset** once. That page keeps team/student ids in browser localStorage; after a rollover those ids are stale.
13. Collect new event rankings (CSV import at `/students/event-ranking/import`, or the ranking editor) and run team assignment as usual.

## What is deleted vs kept

| Cleared | Kept |
|---------|------|
| Non-returning students | Returning students (promoted) |
| All teams | Event definitions (national catalog) |
| All event rankings | Notes (including meeting notes by title) |
| All meeting history attendance snapshots | Database backup under `Data/backups/` |
| Event occurrences (when checked) | |

## Backup location

| Environment | Backup path |
|-------------|-------------|
| Local (`dotnet run`) | `WebApp/Data/backups/pre-rollover-*.db` |
| Docker (with `./data:/app/Data`) | Host: `./data/backups/pre-rollover-*.db` (container: `/app/Data/backups/`) |

## Restore from backup (emergency)

1. Stop the application (or `docker-compose stop`).
2. Replace `Data/app.db` (local) or `./data/app.db` (Docker host) with a copy of the `pre-rollover-*.db` file from the backups folder.
3. If needed, restore `CompetitionYear` in `Data/appsettings.json` / `./data/appsettings.json` (or Chapter Settings after restart).
4. Start the application.