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 (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.