Skip to content
Tutorials Center
My learning

Topics

Lesson 72 of 78 ยท Projects

Project: Release Automation Script

Write release.sh: pick the next semantic version from commit messages, build a changelog, tag the release, support dry runs and hotfix release branches, with guard rails.

Cutting a release by hand is a list of small steps that are easy to get wrong: decide the version number, update the version file, write the release notes, commit, tag the right commit, and do not forget anything when you are in a hurry. Every step is mechanical, which makes it a perfect job for a script, and the input the script needs is already in your repository: the commit messages and the existing tags.

In this project you will build release.sh, a Bash script of about 80 lines that works out the next semantic version from commits written in the Conventional Commits style, updates VERSION and CHANGELOG.md, commits and creates an annotated tag. It has a dry-run mode, refuses to run in unsafe situations, and also works on release branches for hotfixes. Along the way you will use git describe, revision ranges, git log --grep and git tag --sort, and practice defensive Bash with set -euo pipefail.

The script follows the same conventions as the previous project, A Repository From Scratch: commit subjects start with feat:, fix:, docs:, chore: and so on, and a ! before the colon (feat(cli)!:) marks a breaking change. We only need to read the commit subjects, never to modify history.

The rules the script implements

Semantic versioning has three numbers, MAJOR.MINOR.PATCH. The script decides which one to raise by the most significant change found in the commits since the last tag:

Commit subject Meaning Version bump
feat(scope)!: ... or any type!: breaking change major (1.4.9 becomes 2.0.0)
feat: ... or feat(scope): ... new feature minor (1.4.9 becomes 1.5.0)
fix: ... or fix(scope): ... bug fix patch (1.4.9 becomes 1.4.10)
anything else (docs, chore, test, ...) no user-visible change none

If a release contains no feat or fix commits there is nothing worth releasing, and the script says so and stops. You can override the automatic choice by passing major, minor or patch on the command line. (Strict semantic versioning treats 0.x versions as unstable, where anything may change; our script keeps it simple and always follows the table.)

Building block 1: version arithmetic in Bash

The foundation is a function that raises one part of MAJOR.MINOR.PATCH and resets the lower parts. Two details are worth learning before you write any release tooling.

First, version numbers are not decimals or strings: v1.10.0 is newer than v1.9.1, but sorted as text it comes first. Use sort -V (version sort) in shell, and --sort=v:refname in Git. Second, ((x++)) returns exit status 1 when x was 0, because the arithmetic value of the expression is 0, and under set -e that silently kills the script. Writing x=$((x + 1)) avoids it.

Bash Semantic version arithmetic in Bash

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The loop prints the three bumps of v1.4.9: patch rolls to v1.4.10, minor resets the patch to give v1.5.0, and major gives v2.0.0. A repository without any tag starts from v0.0.0, so a first feature release becomes v0.1.0. The text sort places v1.10.0 first and v1.9.1 last, which is wrong for versions, while sort -V gets it right. The last two lines show the ((x++)) trap: the first command ends with exit code 1 and never prints "not reached", while the arithmetic expansion version works.

Building block 2: classifying commit messages

The script reads only subjects, using three regular expressions that Bash's =~ operator (and git log -E --grep) understand:

  • breaking: any lowercase type, an optional scope in parentheses, then !:.
  • feature: feat, an optional scope, then : .
  • bugfix: fix, an optional scope, then : .
Bash Classifying commit subjects

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Each commit gets its level, and the function returns the strongest one by checking the breaking pattern first. Notice the three none lines. A docs: commit does not require a release. feature: ... is not a recognized type, and Fix: ... is rejected because the match is case sensitive: a convention is only useful if the tool enforces it, which is the job of a commit-msg hook (Hooks, and the last project in this series). The last block shows the same patterns used with git log -E --grep=..., which is how the changelog sections are produced. Note that --grep searches the whole message, so the ^ anchor matches the start of any line, including body lines; the script is fine with that because the conventions put the type on the subject line.

A BREAKING CHANGE: footer in the message body is another way to mark a breaking change in the Conventional Commits specification. Our script only looks at subjects to stay short. To support footers, read the full message with git log --format=%B and test it for a line starting with BREAKING CHANGE:.

The script

Here is the complete release.sh. It is created by a here-document in the next example, so you can read it there, in order, with the numbered comments. In outline:

  1. Safety checks. The working tree must be clean (git status --porcelain prints nothing), and the current branch must be main or release/*. A release from a random experiment branch is almost always a mistake.
  2. Find the last release. git describe --tags --abbrev=0 --match 'v[0-9]*' prints the nearest tag reachable from HEAD that looks like a version. Reachable is the key word: on a release branch it finds that branch's own history, not tags from newer work on main. With no tag at all the script starts from v0.0.0 and uses the whole history as the range. The commit subjects in last..HEAD are read into an array with mapfile.
  3. Decide the bump from the classification above, or take it from the argument.
  4. Compute the new version with the arithmetic from building block 1. A tag with that name must not exist yet.
  5. Build the release notes. The section function runs git log --no-merges --reverse -E --grep=... --format='- %s (%h)' last..HEAD and strips the type(scope): prefix with sed. notes prints a heading and the three sections (breaking changes, features, fixes), leaving out empty ones. The date comes from RELEASE_DATE if set, which makes the output reproducible in tests, and from date otherwise.
  6. Dry run or real run. In dry-run mode the script prints the plan and the notes and exits before changing anything. Otherwise it writes VERSION, prepends the notes to CHANGELOG.md (building a new file and moving it into place, so a failure never leaves a half-written changelog), makes a chore(release): vX.Y.Z commit and creates the annotated tag on that commit.

Stage 3: from commits to tagged releases

The example below creates the project, writes release.sh, and then makes four releases: a dry run, the first real release, an automatic patch release, and an automatic major release caused by a breaking commit. The helper release just runs ./release.sh with a fixed release date and a fixed commit date.

Bash Stage 3: dry run and three releases

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Walk through the output:

  • The dry run shows v0.0.0 -> v0.1.0 (minor) because the history contains a feat: commit, prints the notes it would add, and changes nothing. Running it first is how you check the result of a release before making it.
  • The first release printed released v0.1.0 and created the commit and the tag. git tag -n1 at the end lists three tags with their messages, newest first thanks to --sort=-v:refname.
  • The second release found a docs: and a fix(cli): commit since v0.1.0, and chose a patch bump to v0.1.1. The docs: commit does not appear in the notes, because the script only lists breaking changes, features and fixes.
  • The third found feat(cli)!: and jumped to v1.0.0. In CHANGELOG.md it appears under "Breaking changes", with the prefix stripped.
  • git describe prints exactly v1.0.0, because HEAD is the tagged commit.

Because the tag points at the chore(release) commit, the checked-out code at the tag already contains the right VERSION and CHANGELOG.md. That is the main reason to commit first, then tag.

Stage 4: a hotfix on a release branch, and the guard rails

main is now at 1.0.0, but some users are still on 0.1.x and need a bug fix. Releases from main can't help them, and releasing main would force them to take the breaking change. The standard answer is a release branch: git switch -c release/0.1 v0.1.1 starts a branch at the old tag. The fix is committed there, and the same script runs on that branch. Because git describe only sees tags reachable from HEAD, it finds v0.1.1 and produces v0.1.2, a patch release that knows nothing about 1.0.0. The graph afterward shows the two lines of history diverging at the v0.1.1 commit.

(In a real project you would also apply the fix to main, usually with git cherry-pick -x, see Cherry-Pick; we skip it to keep this example short.)

The last part of the example exercises the guard rails, the situations the script must refuse: a dirty working tree, a branch that is neither main nor release/*, a repository with nothing new since the last tag, and a bad argument. Each prints a message on stderr and exits with a non-zero status (1 for a refused release, 2 for wrong usage), so another script or a CI job can detect the failure. 2>&1 in the example merges stderr into the output so you can see the messages and the codes together.

Bash Stage 4: hotfix branch and guard rails

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

In the output, the graph has two branches off v0.1.1: main goes to v1.0.0 while release/0.1 goes to v0.1.2. The four guard-rail runs print, in order, the working tree is not clean, release from main or release/*, not 'experiment', and no commits since v1.0.0 (twice, once plain and once with minor --dry-run, because the check for new commits comes before the dry-run branch), and last the usage message with exit code 2.

Taking it further

  • Push the result: git push origin main "$new" (a tag is not pushed unless you name it or use --follow-tags). Keep pushing outside the script until you trust it, or add a --push option.
  • Run it in CI on every merge to main and let it publish packages. Because it only reads Git, it works in any pipeline.
  • Enforce the commit format with a commit-msg hook so the classification never meets a malformed subject (Quality Gates with Hooks).
  • Add a test: create a temporary repository like the examples above, run the script, and assert on the tag name and the content of CHANGELOG.md. Because the date is injectable, the output is deterministic.
  • Use a signed tag (git tag -s) once you have a signing key (Signing and Security).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A repository has the tag v2.3.1 and three new commits: docs: fix a typo, fix: handle null and feat: add export. What does release.sh choose?

    The strongest change wins. A feat commit means a minor bump, which resets the patch number, so v2.3.1 becomes v2.4.0. The fix and the docs commit do not change that.
  2. 2. Why does the script use x=$((x + 1)) rather than ((x++))?

    An arithmetic command returns 1 when the expression evaluates to 0. The post-increment of 0 evaluates to the old value 0, so set -e treats it as a failure.
  3. 3. How does git describe --tags --abbrev=0 --match 'v[0-9]*' behave on a release branch?

    describe walks back from HEAD and reports the closest reachable tag. On release/0.1 that is v0.1.1, even though main has v1.0.0.
  4. 4. Why does the script create the tag after the chore(release) commit instead of before it?

    The release commit holds the updated VERSION and CHANGELOG.md. Tagging that commit means anyone who checks out the tag gets files that match the version.
  5. 5. What does the dry-run mode do?

    In dry-run mode the script exits before it writes any file, makes any commit or creates any tag.

Summary

  • Release steps are mechanical and live in Git data: tags give the last version, commit subjects give the kind of change.
  • git describe --tags --abbrev=0 finds the nearest reachable tag; last..HEAD is the set of commits in the release; sort -V and --sort=v:refname order versions correctly.
  • A release script should check its preconditions (clean tree, right branch, new commits, unused tag), offer a --dry-run, and exit with meaningful status codes.
  • Commit the version bump and changelog first, then create an annotated tag on that commit.
  • Hotfixes use a release branch started at the old tag; the same script works there because describe follows reachability.
  • In Bash, prefer x=$((x + 1)) to ((x++)) under set -e, and write files atomically by creating a new file and moving it into place.

Next: Project: Build a Tiny Git