Quartz 5

Lab: generate and review release notes from Git history

Properties1
tagslab, az-400, documentation, release-notes, git

4 min read

Lab: generate and review release notes from Git history

Outcome

Create a disposable repository with conventional-style commits and an annotated baseline tag, generate draft release notes from the exact commit range, correct a misleading draft, then publish a training release. Git history supplies evidence; it does not decide whether a change is safe, breaking, or customer-visible.

Before you begin

Use a training repository and configure a non-production Git identity. The starting tag defines the range. Do not generate release notes from an unreviewed branch or use generated text as a substitute for security review.

git init azlearn-release-notes && cd azlearn-release-notes
git config user.name 'Training User'
git config user.email '[email protected]'
printf '# Training service\n' > README.md
git add README.md && git commit -m 'chore: establish baseline'
git tag -a v0.1.0 -m 'Training baseline'

Do

  1. Make three small, separate commits with messages that declare intent:

    printf 'login validation\n' > login.txt
git add login.txt && git commit -m 'fix(auth): reject empty login name'
printf 'receipt endpoint\n' > receipt.txt
git add receipt.txt && git commit -m 'feat(api): add training receipt endpoint'
printf 'migration note\n' >> README.md
git add README.md && git commit -m 'docs: explain training migration'

  2. Generate a deterministic draft from the tag range. Keep the hash and subject so a reviewer can trace every bullet:

    git log v0.1.0..HEAD --pretty=format:'- %h %s' > RELEASE-NOTES-DRAFT.md
cat RELEASE-NOTES-DRAFT.md

  3. Edit the draft into RELEASE-NOTES.md. Group customer-visible changes, state the intended version and release date, link each significant item to its commit or pull request, and explicitly label known limitations. Omit internal churn that does not help a reader decide whether to upgrade.

  4. Compare the finished notes to git log v0.1.0..HEAD --name-status. Check that the API feature and authentication fix are accurately represented, that no non-existent migration was claimed, and that no sensitive value appears in the notes.

  5. Create a reviewed annotated training tag and, in GitHub, draft a release from that tag. Use Generate release notes only as a second draft. Compare its pull-request list with your range-based notes, correct differences, then publish the training release.

Verify

Record the baseline tag, exact commit range, generated draft, reviewer correction, final notes, and release URL. You should now understand: a tag marks a release boundary; git log A..B selects changes reachable from B but not A; generated release notes need editorial and security review.

Break and fix

  1. Intentionally use the wrong starting tag or HEAD~1 as the range. Show that the draft omits or includes the wrong changes. Restore v0.1.0..HEAD and regenerate.
  2. Add a training commit whose message overstates a change, such as feat!: remove old API, while the file does not remove it. Let the generated draft include it, then correct the release note based on the diff and explain why commit messages are inputs, not proof.
  3. Add a fake token-looking string to a commit message in this disposable repository. Before publishing, remove it from the draft, revoke any real credential if one was ever exposed, and follow the host’s sensitive-data-removal procedure. Do not normalize secrets appearing in release notes.

Scenario practice

  1. Configure: A hotfix branch contains two fixes and one reverted experiment. Which tag range and review steps produce accurate notes?
  2. Diagnose: A generated release includes a pull request that was not deployed. Which tag, merge, and deployment evidence do you inspect?
  3. Distinguish: Contrast a Git tag, a GitHub release, a changelog file, and a deployment record. Which proves code selection, which communicates it, and which proves an environment received it?

Clean up

Delete the training repository or release after recording the evidence. Remove all test artifacts and tags from any shared training remote. Never delete a production release merely to practice this cleanup.

Sources and re-audit

Re-audit when Git range semantics, release generation, or repository release permissions change.

Docs as code · Release notes · Git · Process path · All labs

Graph View

Backlinks