Skip to main content

Release and Migration Clinic

Retrieval Prompts​

  1. State the three rules of Semantic Versioning.
  2. Name the four expand/contract steps and what each makes reversible.
  3. What does SLSA Build Level 2 guarantee that Level 1 does not?
  4. Signing proves provenance -- what does it not prove?
  5. Why must a migration be a separately shippable release from the code that uses it?

Compare and Distinguish​

Separate these pairs clearly:

  • tag vs digest as artifact identity
  • MAJOR bump vs MINOR bump (for a new required request field)
  • keyless Sigstore signing vs GPG-key signing
  • expand/contract vs "run the migration during maintenance window"
  • changelog vs release notes vs git log

Common Mistake Check​

For each, identify the error:

  1. "We ship the code change and the column drop in the same commit."
  2. "This release is v2.3.0 -- we renamed an endpoint but it's backward compatible because old clients can still call it."
  3. "We run migrations in the app's startup so it's always up-to-date."
  4. "We sign images with a key committed to the repo so CI can use it."
  5. "The tag v1.2.3 in our registry -- I updated it last week."

Mini Application​

Task 1 -- Ship a release. Pick a service. Do all of:

  • write the next changelog entry in Keep-a-Changelog format
  • decide the version bump under SemVer and justify
  • create a signed tag (git tag -s) or document why you cannot yet
  • draft release notes (human-facing, < 200 words)

Task 2 -- Expand/contract migration. Take this real change: rename the users.email_addr column to users.email. Write out the full sequence:

  • Release 1 -- Expand (SQL + code diff)
  • Release 2 -- Switch reads (code diff)
  • Release 3 -- Stop writing old (code diff)
  • Release 4 -- Contract (SQL)

For each release, state:

  • what production failure is prevented by not combining it with the next step
  • the rollback path at that step

Task 3 -- Signing. Add a signing step to an existing pipeline that:

  • uses Sigstore keyless OIDC signing (or documents why you cannot)
  • signs the built image digest
  • verifies the signature in the deploy stage, refusing to deploy if verification fails

Evidence Check​

You are done when:

  • your release has a version number that would not change if you changed your mind about the changelog wording
  • your migration is four separately deployable PRs, each of which you could roll back independently
  • your pipeline refuses to deploy an unsigned image
  • you can answer "who built this image and from what commit?" for any artifact in your registry