Homework 5

Evolve Without Downtime

Change a live system's API and stored data while existing clients and live operations keep working.

API evolution Data evolution Idempotency Availability

Release Date Nov 2, 2026

Due Date Nov 15, 2026

Weight 200 pts

Overview

Tartan Tickets now has stored data, existing clients, and simulated customers using it around the clock. The development team has asked for a change to both the API (the contract clients use to talk to the service) and the data the application stores. You will make that change without taking the system offline, losing data, or breaking existing clients.

In the first week, plan the transition and deploy an intermediate state, in which old and new behavior run safely together. In the second, finish the change and stop using the old representation of the data.

🎯 Learning Goals

After completing this assignment, you should be able to:

• Change an API without requiring existing clients to change
• Migrate stored data while the system keeps accepting reads and writes
• Plan a change as a sequence of deployments that can each be checked
• Prevent retried requests from causing duplicate side effects
• Retire a legacy representation once nothing depends on it

🚩 Checkpoints

Checkpoint	Points	Due	Last accepted
Checkpoint A: Safe Intermediate State	80 pts	Nov 10, 2026	Nov 14, 2026
Checkpoint B: Completed Transition	120 pts	Nov 15, 2026	Nov 19, 2026

Due and last-accepted times are 11:59 p.m. Eastern Time.

Late Days Carry Across Checkpoints

HW5A and HW5B use the same course-wide late-day balance. Each late day used for HW5A moves your HW5B due time one day later; staff will record the new due time in Canvas. HW5B's November 19 final submission deadline stays fixed. Staff will adjust deadlines without charging late days if a staff delay or course-tool outage prevents you from working.

Course Support

Staff will open a GitHub issue on your repository when HW5 is released. It describes the requested change, why the team wants it, the existing behavior that must keep working, and the legacy representation: the current form of the data that the change replaces. The issue is the authoritative description of what to build; this handout describes how you will be assessed. If you do not see the issue on release day, contact course staff.

The issue says what the system must do, not how to get there. How you store the new data, keep old and new representations consistent, migrate existing data, and sequence your deployments is up to you.

Simulated course traffic from HW4 continues throughout this assignment, and staff will also place orders on a regular schedule. The data already stored in production is part of what you must migrate.

When Staff Use the New API

Until the HW5B last-accepted time (November 19), staff and simulated traffic use only the existing API, so test the new behavior yourself. After that, staff test the new behavior in the issue, including retries long after the original request.

Automatic Schema Changes

The starter code sets synchronize: true in database/src/data-source.ts, which lets each service change the database schema automatically when it starts. Find out what that means for a deployment in which old and new versions of your services run at the same time, and account for it in your plan.

Requirements

Requirement 1: Plan the Transition

Before deploying your first change to the database schema or stored data, commit hw5/PLAN.md to main using the template. Plan the change as a sequence of deployments, from the current system to the final one. For each deployment, identify which versions of your services and data may run at the same time, and what you will check before taking the next step.

If a check fails, do not take the next step until you have resolved it or committed a revised plan. If you change your steps or checks, commit the updated plan before acting on it. Do not rewrite earlier commits of the plan.

Requirement 2: Reach a Safe Intermediate State

By Checkpoint A, deploy one of the steps in your plan in which:

• The old and new representations coexist in production, and the running system uses the new one.
• Existing behavior listed in the issue is unchanged.

You choose which step to submit; it does not need to include every part of the new behavior. You may keep deploying later steps after you submit.

Requirement 3: Complete the Transition

By Checkpoint B, every acceptance criterion in the issue must hold, for data created before, during, and after the transition. Migrate the existing data into the new representation and serve the new behavior from it.

Commit a script or query that checks whether all existing data has been migrated, and include its output against production in your report. Use it to decide when you can stop using the legacy representation.

Add tests to your normal CI that cover the existing behavior, the new behavior, migrated data, and the retry behavior the issue requires.

Requirement 4: Keep the System Available

Make the change without planned downtime, a write freeze, or deleting or reseeding data. Make it over several deployments, not one, and record each in your report's deployment log.

A Working Final State Is Not Enough

Staff grade the path as well as the result. A sustained outage or elevated error rate during the transition costs availability credit even if the final system works.

Requirement 5: Retire the Legacy Representation

By Checkpoint B, stop reading and writing the legacy representation named in the issue. Then decide whether to keep it unused or remove it, based on evidence such as remaining readers, data completeness, and what you would need to recover from a mistake.

Documents and Evidence

Copy the templates below into hw5/PLAN.md and hw5/REPORT.md and replace the prompts. Short bullets are enough. Complete the report's Checkpoint A section for HW5A and its Checkpoint B section for HW5B.

In the deployment log, record every production deployment for HW5, including any whose check failed. Link each entry to a record staff can open that shows the deployed commit and time, such as a CD run on GitHub. If your pipeline deploys from the VM and leaves no record on GitHub, commit a copy of its record to hw5/deployments/ and link that.

Do not include secrets, payment details, or customer personal data in either document. Staff grade your repository, running system, and evidence as of your latest accepted Canvas submission. Keep your system running through November 21 at 11:59 p.m. Eastern, even if you submit HW5B earlier.

Template: hw5/PLAN.md

# HW5 Plan

## Steps
Copy this block for each production deployment, in order.

### Step 1: Short name
- What changes in the code, schema, or data?
- Which versions of your services and data may run at the same time?
- What will you check before the next step, and what problem would it catch?
- How would you undo this step?

## Irreversible step
- Which is the first step that redeploying older code cannot undo, and how would you recover after it? If none, explain why.

## Alternative
- What is one other reasonable design, and why did you not choose it?

Template: hw5/REPORT.md

# HW5 Report

## Deployment log
One line per production deployment, oldest first:

- Step 1, `a1b2c3d`, https://github.com/.../actions/runs/...: check passed

## Checkpoint A: Intermediate state
- Submitted plan step:
- Why existing clients and live operations are safe in this state:

## Checkpoint B: Completed transition
- Completeness check: Link to your script or query, and its output before you retired the legacy representation.
- Tests: Links to the tests for existing behavior, new behavior, migrated data, and retries.

### Legacy representation
- Evidence that nothing reads or writes it:
- Kept unused or removed, and why:
- How you would recover if that decision turned out to be wrong:

### Reflection
- How your plan changed, if at all:
- One remaining risk or uncertainty:

Add an ## HW5 entry to DISCLOSURE.md describing any AI tools used and how, or stating that you used none. Update it before HW5B to cover the complete assignment.

Submission and Deliverables

Finish the documents on main and check that CI passes. Deploy that commit through your CD pipeline to your registered production target, then submit its GitHub URL in Canvas. Use these checklists to check your work.

HW5A: Safe Intermediate State

Due Tuesday, November 10 at 11:59 pm ET.

Last accepted Saturday, November 14 at 11:59 pm ET.

• Commit hw5/PLAN.md to main using the template before deploying your first change to the database schema or stored data.
• Deploy a step from your plan in which the old and new representations coexist in production and existing behavior is unchanged.
• Complete the Checkpoint A section of hw5/REPORT.md using the template.
• Add an HW5 entry to DISCLOSURE.md.
• Submit the GitHub commit URL in HW5A on Canvas.

Open HW5A in Canvas→

HW5B: Completed Transition

Due Sunday, November 15 at 11:59 pm ET.

Last accepted Thursday, November 19 at 11:59 pm ET.

• Complete the change requested in the issue.
• Commit a script or query that checks whether all existing data has been migrated, and include its output in your report.
• Stop reading and writing the legacy representation named in the issue, and decide whether to keep it unused or remove it.
• Add tests for the transition to your normal CI and check that CI passes on main.
• Complete the Checkpoint B section of hw5/REPORT.md.
• Deploy your submitted commit and keep it running through November 21.
• Update the HW5 entry in DISCLOSURE.md to cover the complete assignment.
• Submit the GitHub commit URL in HW5B on Canvas.

Open HW5B in Canvas→

Grading

Each item is pass/fail. It earns its points only when everything it describes holds and staff can check it; claims without supporting evidence do not pass.

The assignment is worth 200 points.

HW5A — Safe Intermediate State80 pts

• `hw5/PLAN.md` was committed before the first deployment that changed the schema or stored data.5 pts
• Each step in the plan says what changes, which versions of services and data may run at the same time, and how to undo it, and accounts for the mixed versions that can actually occur, including automatic schema changes.10 pts
• Each step has a check to run before the next step that would catch the problem it names.5 pts
• The plan correctly identifies the first step that redeploying older code cannot undo and how to recover after it, or correctly explains why no step is irreversible.5 pts
• The plan describes one other reasonable design and why it was not chosen.5 pts
• The submitted commit carries out a step from the plan, and its linked deployment record shows it was deployed to production.10 pts
• In the submitted commit, the old and new representations both exist and the running system writes or reads the new one.15 pts
• After the submission, the existing behavior listed in the issue keeps the same fields and meanings.15 pts
• No stored data was deleted or reseeded.5 pts
• The Checkpoint A report and deployment log are complete, and each logged deployment links to a record that identifies its commit and time. DISCLOSURE.md has an HW5 entry.5 pts

HW5B — Completed Transition120 pts

• The new behavior in the issue works for data created before, during, and after the transition, and its results agree with the external system of record the issue names.15 pts
• The new behavior enforces the access rules in the issue and returns no data beyond what the issue lists.5 pts
• Repeating the operation the issue requires to be safe to retry returns the first response and causes no new side effects, and requests that do not ask for this behave as before.10 pts
• A retry still returns the first response and causes no new side effects for as long as the issue requires.5 pts
• The existing behavior listed in the issue still keeps the same fields and meanings.10 pts
• The new behavior is served from the new representation, not computed from the legacy one.10 pts
• The committed completeness check covers every existing record, and the reported output shows nothing missing before the legacy representation was retired.10 pts
• Simulated traffic kept working throughout the transition, with no outage or sustained rise in errors above your HW4 baseline beyond brief spikes during logged deployments.10 pts
• The change passed through at least one intermediate state, without planned downtime, a write freeze, or deleted or reseeded data.5 pts
• Each logged deployment matches a plan step or a revision committed before it, and no step followed a failed check before the failure was resolved or the plan revised.5 pts
• CI tests cover the existing and new behavior, each with at least one test that would fail if that behavior broke, and CI passes on the submitted commit.5 pts
• CI tests cover migrated data and retries, each with at least one test that would fail if that behavior broke.5 pts
• No code uses or sets the value of the legacy representation named in the issue, and data created after the submission is not stored in it.10 pts
• The report says whether the legacy representation was kept unused or removed, supports the decision with evidence, and explains a credible way to recover if it was wrong.10 pts
• Your plan, report, and AI disclosure are complete and follow the templates. The submitted commit is running in production, and submitted evidence contains no sensitive data.5 pts