Skip to main content

Release Notes and Change Log for Future You

What This Concept Is​

Release notes for a capstone are not marketing, and they are not a broadcast. They are a short note written to one reader: your future self, sometime between six months and three years from now, trying to figure out what happened.

A release note has three structural sections, under 10 lines of prose:

  • Changed: bullet list of user-visible changes (not every commit; the user-visible ones)
  • Why: one sentence of intent per change, or one sentence for the whole release
  • Risk: anything that could have gone wrong in this deploy, whether it did or not -- cost increases, new migrations, new external dependencies, loosened permissions

A change log is the append-only file of release notes: CHANGELOG.md, newest at the top. Keep-a-Changelog and Conventional Commits are useful conventions; neither is mandatory. The mandatory piece is that each shipped deploy has one entry, written within the hour of the deploy, not invented a week later.

Why It Matters Here (In the Capstone)​

By the capstone defense, you will have made 30+ deploys. You will not remember why you shipped what in week 8. The release note is how you remember. It is also the artifact a reviewer scans first -- it tells them whether you treat deploys as events or as accidents.

Release notes pair with DORA's "deployment frequency" metric. Counting deploys only has meaning if each deploy is individually legible. A reviewer who sees "30 deploys" with three release-note entries does not see 30 deploys; they see three, plus 27 question marks.

Concrete Example(s)​

A real-looking entry for CHANGELOG.md:

## v1.3.0 -- 2026-05-14 (prod)

**Commit:** `a3b5c7d`  
**Image:** `gcr.io/capstone-prod/api:v1.3.0`  
**Terraform run:** #247

### Changed
- Added `/billing/invoices` endpoint (behind `newBillingFlow` flag, default off)
- Cloud Run min instances raised from 0 -> 1 to remove cold-start 500ms
- Tightened CI deploy role: removed `storage.buckets.create` (no longer needed)

### Why
- First customer-facing billing slice; min-instances raised to pass p95 smoke test under burst; CI role tightening is routine least-privilege cleanup

### Risk
- Cloud Run cost increases ~$6/mo due to min-instances=1 change
- Billing endpoint behind flag; flip deferred until next deploy after 24h smoke soak
- Role tightening could block a future manual `apply`; documented in `library/raw/decisions/007-ci-role.md`

### Verified
- smoke.sh ok (2s, prod)
- manual: flag off -> old billing page renders; flag on (staging only) -> new page renders with seeded data

A template you can commit at library/raw/release-notes-template.md so every entry is structurally identical:

## vX.Y.Z -- YYYY-MM-DD (env)

**Commit:** `SHA`  
**Image:** `IMAGE:TAG`  
**Terraform run:** #NNN

### Changed
- ...

### Why
- ...

### Risk
- ...

### Verified
- smoke.sh ok
- manual: ...

A pipeline step that generates a stub after a successful prod deploy, leaving the Why/Risk for the human to fill in:

- name: Draft release-note stub
  if: success() && github.ref == 'refs/heads/main'
  run: |
    ./scripts/draft-release-note.sh \
      --version ${{ github.ref_name }} \
      --commit ${{ github.sha }} \
      --image $IMAGE \
      >> CHANGELOG.md

Common Confusion / Misconceptions​

  • "Commit messages are release notes." Commit messages are the raw input. A release note is a summary grouped by what a reader needs: what changed, why, what risk. Dumping git log --oneline into a file is not a release note -- it makes the reader do the work. A 40-line auto-generated list is actively worse than a 3-bullet hand-written summary.
  • "I'll write release notes later." Release notes written later are invented. The context ("why did I raise min-instances?") evaporates within 48 hours. Write them as part of the deploy, not as a debt.
  • "Release notes are for users." For a public product, partially. For a capstone, the audience is your reviewer and your future self. Write accordingly -- technical and direct, not marketing.
  • "SemVer matters for a capstone." Not much. Date-based tags (2026-05-14-01) or simple increments are fine. If you use SemVer, follow its rules (breaking = major); if you don't, don't pretend to.
  • "A release note is optional when the deploy is small." A small deploy with no release note looks identical to an accidental deploy. The point is the artifact, not the size of the change.

How To Use It (In Your Capstone)​

  1. Commit CHANGELOG.md and library/raw/release-notes-template.md in the first week.
  2. In the pipeline, after a successful prod deploy, run a script that appends a stub from the last main tag's commits.
  3. Finish the stub by hand within the hour of the deploy. This is non-negotiable for the capstone's grade; if you deferred a deploy rather than write the note, that is a win.
  4. Include Commit, Image, and Terraform run at the top of every entry. Three lines of metadata turn an archaeological dig into a one-minute search.
  5. Write Risk honestly; "could break rollback path" is a legitimate note that thanks your future self.
  6. Use Keep a Changelog structure only if it helps you. A hand-written three-bullet note is strictly better than an auto-generated 40-bullet one.
  7. Read the last three entries before a prod deploy -- it is a cheap pre-flight for "did we promise something I should double-check?"

What a Release Note Is Not​

  • Not a press release. Nobody reads capstone release notes for marketing value. Plain, short, direct.
  • Not an apology. If a deploy went wrong, the note records what shipped, not your feelings about it. Incident notes are a separate artifact (under library/raw/incidents/).
  • Not an audit log. CI already records what shipped. The release note records why and what risk you accepted.
  • Not optional. A deploy without a release note is a deploy that did not happen from your future self's perspective.

See also (integrative)​

Check Yourself​

  1. What is the last entry in your CHANGELOG.md, and does it include a Why and a Risk?
  2. Could you answer "what did we ship in week 8?" in under 30 seconds by reading the changelog?
  3. When did you last fail to write a release note within an hour of deploy? What broke, and why?
  4. Can you trace the last release note to a commit SHA and an image tag in under a minute?
  5. Does each entry's Risk list something honest, or are they all empty?
  6. What is the oldest entry you would trust to deploy from, in reverse -- rolling back the exact change it describes?

Mini Drill or Application (Capstone-scoped)​

  1. Three back-dated entries. Write release notes for the last three commits to main as if you had shipped them all. If you cannot fill Why for any of them, that commit shipped without intent -- flag it as a process bug and fix the workflow.
  2. Stub generator. Commit scripts/draft-release-note.sh that emits the template populated with commit, image, and Terraform run. Run it manually once; next deploy it runs in the pipeline.
  3. Hour-rule test. At your next prod deploy, set a 60-minute timer. If the release note is not finished within the hour, note what blocked you and fix that blocker before the next deploy.

Source Backbone​

Capstone deployment applies cloud, delivery, and operations material. These books are the source backbone for the delivery decisions.