Skip to content
Clawdemy

Releases and tags

What this lesson covers

Section titled “What this lesson covers”

L10 teaches the mechanics of formal releases, how a commit becomes “v2.0” with a marker, a name, and release notes that users can engage with.

Four load-bearing ideas:

  1. A tag is a named pointer to a specific commit that never moves. Branches advance; tags are fixed. For releases, always use annotated tags (git tag -a) not lightweight tags.

  2. Semantic versioning (semver) is the industry contract. MAJOR.MINOR.PATCH. Major = breaking change. Minor = backward-compatible feature. Patch = backward-compatible fix. Users read the version and know the upgrade risk.

  3. Release notes serve four audiences, users, operators, developers, auditors. Each section of a canonical release note (Highlights, Breaking changes, New features, Bug fixes, Migration notes) addresses different audience needs.

  4. Releases work differently across the four L9 workflows but the underlying mechanics (tag + notes + announcement) are the same. GitHub Flow tags main commits; GitFlow tags after release-branch QA; Trunk-based often automates; Forking puts the maintainer in the release authority role.

By the end of L10, the reader will be able to

Section titled “By the end of L10, the reader will be able to”
  • Create annotated tags with git tag -a vX.Y.Z -m "..."
  • Push tags with git push origin vX.Y.Z or --tags
  • Choose the right semver bump (major / minor / patch) for a given change
  • Write a release note covering all relevant sections
  • Set up GitHub Releases pages and auto-generated release notes
  • Use pre-release identifiers for alpha/beta/rc cycles
  • Identify how each of the four L9 workflows handles releases
  • Reason about cadence and automation choices

Prerequisites

Section titled “Prerequisites”
  • L1-L8 (foundations)
  • L9 (you’ll see how releases differ across the four workflows)
  • A GitHub account with at least one repo to practice on

Reading map

Section titled “Reading map”

L10 is content-dense by design. Read in three passes:

Pass 1, the mechanics: Tags + semver + the basic command set. After this, you can create and push a tag.

Pass 2, the release notes craft: The canonical structure + writing tips + auto-generation tools. After this, you can write a release note worth reading.

Pass 3, workflow integration + scenarios: How releases work in each L9 workflow + concrete scenarios + multi-agent foreshadowing. After this, you can pick a release cadence for your team.

What this lesson deliberately does not cover

Section titled “What this lesson deliberately does not cover”
  • The specifics of npm/PyPI/Maven/Cargo publishing (covered by their respective docs)
  • Container registry pushes (Docker Hub, GHCR; release tag = container tag, often)
  • Deployment pipelines triggered by tags (covered tangentially; deeper treatment beyond T7)
  • Signed tags with GPG (security-focused; covered in Pro Git Ch. 7 if needed)

Estimated reading + practice time

Section titled “Estimated reading + practice time”

30-40 minutes for reading. 25-35 minutes for practice (includes creating, pushing, and “releasing” a real tag in a sandbox repo).

Total: about 55-75 minutes including practice.