Semantic versioning explained: tags and GitHub releases

You

Support wants to tell customers "fixed in version so-and-so", like app update notes. Which version was #134?

Daniel

Honest answer: none. Look at the Tags page. There are four old tags, v1.0.0 to v1.3.0, which I set by hand for big launches. The last one sits on the cat treats bundle.

Alex Tutor

A tag is a fixed name for one commit. A branch moves forward with every new commit; a tag stays exactly where it was put. That's why versions are tags.

Alex Tutor

main and its only recent tagv1.3.0 marks 8be2f70. Everything merged after it, including #134, is on the live site but not in any version.

8be2f70Add cat treats bundlev1.3.0
6f2c8a1Raise free-delivery threshold to 1000 UAH (#133)
a7d93e4Rewrite delivery page copy (#132)
d51c7e8Fix checkout button after cart edits (#134)
3b8e1f6Add autumn sale banner (#136)
9c4a2d7Add loyalty points behind a flag (#155)main

You

So the tag is like a bookmark in the history, and main has moved five commits past it.

Daniel

Right. And tags can technically be deleted and recreated, but you never move a published one. People and tools rely on v1.3.0 meaning the same thing forever.

Alex Tutor

So from today the team tags a release every Thursday: the current main, which is already live, gets a version number and notes. Urgent fixes get their own version right away.

Alex Tutor

Question 1

Support asks: "Was the checkout fix, #134, released in v1.3.0?" What is the correct answer on Thursday morning?

main on Thursday morning

8be2f70v1.3.0
6f2c8a1#133
a7d93e4#132
d51c7e8#134
3b8e1f6#136
9c4a2d7#155main

Choose one answerYes: v1.3.0 is the newest tag, so it includes everything in mainNo: v1.3.0 points at 8be2f70, and #134 came later; no tag contains it yetYes: the tag moves forward with main until the next tag is createdNo: #134 is not live yet

You

Why v1.3.0 and not simply "version 13"?

Alex Tutor

It's semantic versioning, SemVer: MAJOR.MINOR.PATCH. Each number tells you what kind of change happened. PATCH goes up for fixes, MINOR for new features that break nothing, MAJOR for changes that break something people rely on.

When a number goes up, the ones to its right reset to zero. After 1.3.0, a fix gives 1.3.1, a new feature gives 1.4.0, a breaking change gives 2.0.0.

Daniel

The rules at semver.org are written for software other programs depend on. For a website we decided ourselves: MAJOR if old links, saved carts or partner integrations stop working. We hope never to need it.

You

And the v in front?

Daniel

Just a common habit for tag names. The version itself is 1.3.0. Sometimes you'll also see 2.0.0-beta.1: a pre-release, a test version that comes before the real 2.0.0.

Alex Tutor

Question 2

The last release is v1.4.0. Match each next release with the version it should get under CatChow's rules.

Tap an answer, then tap the row it belongs to. You can also drag.

Only a fix for a wrong link in the footer
A new gift note field at checkout
New page addresses; all old product links stop working
A test build of the new catalogue before its real release

Answers left to place

You

One trap I can already see: is 1.4.10 older than 1.4.9? Alphabetically it would be.

Alex Tutor

Each part is a whole number, compared left to right. Ten is more than nine, so 1.4.10 is newer. And a pre-release is older than its release: 1.5.0-beta.1 comes before 1.5.0.

Daniel

GitHub doesn't always sort tags that way on the tags page, by the way. Trust the numbers, not the list order.

You

Numbers, not alphabet. Got it.

Alex Tutor

Question 3

Put these versions in order from oldest to newest.

Tap an item, then tap where it should go. You can also drag or use the arrows.

Alex Tutor

Thursday afternoon. Since v1.3.0 there are two new features, the sale banner and the hidden loyalty groundwork, so it's a MINOR release: v1.4.0. Daniel opens Releases from the repository page.

Daniel

As of 2026: Draft a new release, then type v1.4.0 as a new tag, target main. GitHub creates the tag when I publish. Previous tag v1.3.0, and then the magic button: Generate release notes.

Alex Tutor

What Generate release notes produced

## What's Changed
* Raise free-delivery threshold to 1000 UAH by @catchow-daniel in https://github.com/catchow/website/pull/133
* Rewrite delivery page copy by @catchow-emma in https://github.com/catchow/website/pull/132
* Fix checkout button after cart edits by @catchow-daniel in https://github.com/catchow/website/pull/134
* Add autumn sale banner by @catchow-emma in https://github.com/catchow/website/pull/136
* Add loyalty points behind a flag by @catchow-daniel in https://github.com/catchow/website/pull/155

**Full Changelog**: https://github.com/catchow/website/compare/v1.3.0...v1.4.0

You

Every merged pull request since v1.3.0, with its title and author. So good titles pay off twice.

Alex Tutor

Below the text there's a place to attach files, the assets. GitHub always adds the source code as a zip and a tar.gz; app teams attach the built app. We don't need more.

Daniel

Then two checkboxes. Set as a pre-release for test versions; not today. Set as the latest release: yes. Publish release, and the repository page shows v1.4.0 with a green Latest badge.

Alex Tutor

The two newest tags in catchow/website, Thursday evening

v1.4.0
Latest · on 9c4a2d7 · release notes by Daniel and Sofia
v1.3.0
on 8be2f70 · no release page, tag only

Alex Tutor

Question 4

Which statements about CatChow's new v1.4.0 release are true? Select all that apply.

Choose all that applyThe release page is built on the tag v1.4.0, which points at 9c4a2d7Publishing the release deployed the changes to the siteThe generated notes list the pull requests merged since v1.3.0Latest means it is the newest non-pre-release version, not that it was deployedv1.3.0 now points at the same commit as v1.4.0

You

Support won't understand "Add loyalty points behind a flag". And they must not tell customers about loyalty points yet.

Alex Tutor

That's the difference between a list of pull requests and a changelog: a record of what changed in each version, written for the people who use it. The generated list is raw material, not the finished text.

Daniel

Some teams keep a CHANGELOG.md file with sections like Added, Changed, Fixed. We'll use the release pages as our changelog. I'll also add a small config so the generator groups pull requests by label: bug under "Fixes".

Alex Tutor

So you add a short "For customers and support" part on top, in plain words, and keep the generated list below for engineers.

You

What customers notice, what support should say, and nothing about hidden work.

Alex Tutor

Question 5Short answer · AI-checked task

Write the "For customers and support" part of the v1.4.0 notes (3–5 short lines), based on the generated list above. Loyalty points must not be announced yet.

Write your answer and get a score with feedback from our AI reviewer.

Log in to get AI feedback

You

Wait. #134 went live last Wednesday, and it was "released" today. So at CatChow the release comes after customers already have the change?

Alex Tutor

Yes. For us, merged means live within minutes, and a release is a named snapshot for people to talk about. Three words, but at CatChow two of them usually happen at once.

Daniel

At my old job all three were far apart. Merged into develop, released weeks later, then store review, and even after approval the stores can roll a version out gradually to a growing share of users.

Alex Tutor

And flags split "released" from "visible" even here. #155 is in v1.4.0, and no customer can see it.

You

So when someone asks "is it live?", I first ask myself: merged, released, or visible to customers?

Alex Tutor

Question 6

Match each situation with what customers actually get.

Tap an answer, then tap the row it belongs to. You can also drag.

#134 at CatChow, merged last Wednesday, part of v1.4.0 since Thursday
#155 at CatChow, part of v1.4.0, flag loyalty-points off
Reminders in the app's v2.8.0, approved, on day 2 of a gradual rollout
Step goals merged into the app's develop yesterday

Answers left to place

You

Support just forwarded two messages. Customers see a new "Loyalty points" link in their account menu, and it opens an empty page.

Daniel

My fault. In #155 the loyalty section checks the flag, the menu link doesn't. It's been visible since Tuesday. The fix is two lines.

Alex Tutor

That's a hotfix: an urgent fix to what customers already have. In GitHub flow it isn't a special branch type, just a small pull request into main that jumps the queue.

Daniel

Nothing else has been merged since v1.4.0, so after the fix main is v1.4.0 plus one fix. If a feature had slipped in, it would honestly be v1.5.0.

Alex Tutor

Plan it before Daniel starts: the path to the site, the version, the notes, and what support says to the two customers.

Alex Tutor

Question 7Case · AI-checked task

Plan the hotfix for the loyalty menu link and write its release notes.

Friday, 10:00. Since Tuesday's deploy of #155, customers see a "Loyalty points" link in the account menu that opens an empty page. The programme hasn't been announced; the flag loyalty-points is off, but the menu link ignores it. v1.4.0 was published yesterday and is marked Latest; nothing has been merged since.

CatChow works in GitHub flow: main is protected (pull request, at least one approval, required checks build and test, branch up to date), every pull request gets a preview, and every merge into main is deployed within minutes.

Write: (1) the steps from branch to "fixed on the live site", with who does what; (2) the version number and why; (3) short release notes for support; (4) what support tells the two customers.

Write your answer and get a score with feedback from our AI reviewer.

Log in to get AI feedback

Daniel

Done by 11:30. #158 "Hide loyalty menu link when flag is off", Oscar approved, you and Oscar both checked the preview, squash-merged as e5f81a3, deployed. v1.4.1 is published and now carries Latest.

You

Support's next question, I bet: is the checkout fix in v1.4.1 too? It isn't in its notes.

Alex Tutor

main with two new tagsEach tag marks one commit. v1.4.1 sits later on the same line, so it contains everything in v1.4.0 plus e5f81a3.

8be2f70Add cat treats bundlev1.3.0
6f2c8a1Raise free-delivery threshold to 1000 UAH (#133)
a7d93e4Rewrite delivery page copy (#132)
d51c7e8Fix checkout button after cart edits (#134)
3b8e1f6Add autumn sale banner (#136)
9c4a2d7Add loyalty points behind a flag (#155)v1.4.0
0d7b3c9Check flag before showing menu linkfix/loyalty-menu-link
e5f81a3Hide loyalty menu link when flag is off (#158)mainv1.4.1

Release notes list only what's new since the previous version. But a version contains everything before it on the same line. v1.4.1 is later than v1.4.0, and v1.4.0 contains d51c7e8.

Daniel

Two ways to prove it on GitHub. The compare view, v1.4.0...v1.4.1, shows exactly what was added between the tags: one commit. And as of 2026 a commit's page lists the tags that contain it.

You

So on d51c7e8 I'd see both v1.4.0 and v1.4.1, but not v1.3.0.

Alex Tutor

Exactly. That's the answer support can forward: "fixed in 1.4.0, and in every version since".

Alex Tutor

Question 8

Daniel opens the compare view v1.4.0...v1.4.1. Which pull requests does it show?

Between two tags

d51c7e8#134
3b8e1f6#136
9c4a2d7#155v1.4.0
e5f81a3#158mainv1.4.1

Choose one answer#134, #136, #155 and #158#155 and #158None: the two tags are on the same branchOnly #158

You

And if I only had the release pages?

Alex Tutor

Then read them in order. Find the first version whose notes mention the fix, and remember that each later version keeps it, unless a later note says it was reverted.

Daniel

That "unless" matters. Remember my March revert: a later version can take something back out.

You

So first appearance plus no revert since. Good.

Alex Tutor

Question 9

Support asks: "Is the checkout fix #134 in v1.4.1?" Which ways of checking give a reliable answer? Select all that apply.

Choose all that applyOpen the page of commit d51c7e8 and look at the tags that contain itSearch only the v1.4.1 release notes for #134Find #134 in the v1.4.0 notes, then check that no later release reverts itCheck whether #134 shows MergedLook at the history of main up to the commit tagged v1.4.1

That's module 4: GitHub flow at home, git flow when releases are events, and versions that make "is it live, and in which version?" a question with a one-line answer.

You

And now the loyalty points need a home where the whole team can see what's left before the launch.

Daniel

Issues, labels, a milestone and a project board. That's next module, and you'll make your first change yourself.

Alex Tutor

That’s the lesson. You answered every task — nicely done.

Next lesson: Issues, labels and milestones; linking PRs to issues