Versioning (SemVer) & The Twelve-Factor App
Releases get version numbers so everyone can tell what changed and how risky an upgrade is. The common scheme is Semantic Versioning (SemVer). And a famous checklist — the Twelve-Factor App — captures what makes software easy to build, ship, and run reliably. Both pull together threads from this whole chapter.
A version number you can read turns "should I upgrade?" from a guess into an informed decision. And the twelve factors put names to many habits you've already met.
Two pictures: SemVer is like a movie rating you can read at a glance — telling you instantly whether a change is safe or a big deal — and the twelve factors are a pre-flight checklist a crew runs before every takeoff.
SemVer: MAJOR.MINOR.PATCH
Semantic Versioning gives a release three numbers, like 2.4.1, each with a precise meaning. Bump the MAJOR number for a breaking change (something that could stop existing users' setups from working). Bump the MINOR for a new feature that doesn't break anything. Bump the PATCH for a bug fix. So just reading 2.4.1 → 3.0.0 warns you: this upgrade might break things.
| Part | Bump it when… | Example |
|---|---|---|
| MAJOR | You make a breaking change | 2.4.1 → 3.0.0 |
| MINOR | You add a feature, nothing breaks | 2.4.1 → 2.5.0 |
| PATCH | You fix a bug | 2.4.1 → 2.4.2 |
Changelogs
Alongside the number, a changelog is a human-readable list of what changed in each release — new features, fixes, and especially anything that breaks. The version number gives the headline (how risky); the changelog gives the detail (what actually changed and why). Together they let anyone decide whether and how to upgrade, without reading the code.
The Twelve-Factor App
The Twelve-Factor App is a well-known set of twelve principles for building software that's easy to run reliably, especially in the cloud. You don't need them memorized; you've already met several. A few representative ones: keep config in the environment (not hard-coded), run the app as stateless processes (so you can add or replace copies freely), treat logs as streams (just emit them, don't manage log files), and keep dev and production as similar as possible (the parity idea). They read like a summary of good shipping habits — because they are.
Why It Endures
The twelve-factor app has lasted because it codifies ideas that keep proving useful: software built this way is easier to deploy, scale, and recover. It's not a rigid certification you pass or fail — it's battle-tested guidance, a touchstone teams return to when deciding how to structure an app for smooth operation. Meeting it here ties together the build, environments, config, and releases from across this chapter.
Cadence tags the reminders release 1.3.0 — a new feature, nothing broken, so the MINOR number went up — and notes it in the changelog so everyone knows what shipped. Reviewing their setup against the twelve factors, the team confirms their config lives in the environment and their processes are stateless, so they can run more copies under load without trouble. SemVer and the twelve factors, quietly keeping the release legible and the app easy to run.
- "Version numbers are arbitrary labels." In SemVer each part has a precise meaning — breaking, feature, or fix — so the number itself tells you how risky an upgrade is.
- "A bigger version number just means better software." A MAJOR bump can mean breaking, not better — it warns of incompatibility, not necessarily improvement. Read it as a signal, not a score.
- "The twelve factors are rigid rules or a certification." They're battle-tested guidance, not a law or a badge. Teams use them as a reference for building easy-to-run software, not a checklist to pass.
- SemVer is read on every dependency and release — knowing what the three numbers mean lets you judge upgrade risk at a glance.
- The twelve-factor app is a touchstone reference you'll meet repeatedly in real work, especially around cloud and deployment.
- Together they tie this chapter together: building, environments, config, and releasing all show up in SemVer's meaning and the twelve factors.
Knowledge Check
In SemVer, when do you bump the MAJOR number?
- When you make a breaking change that could disrupt existing users
- When you simply fix a small bug without changing any of the behaviour at all
- When you add a new feature that doesn't break anything at all
- Automatically once every year, regardless of what has changed
What does reading a version jump from 2.4.1 to 2.5.0 tell you?
- A new feature was added, and nothing existing should break
- A breaking change happened that could disrupt existing user setups
- Only a small bug was fixed, with no new feature added at all
- Nothing meaningful, since version numbers are essentially random
What is the Twelve-Factor App?
- A set of twelve principles for software that's easy to build, ship, and run
- A strict official certification that every app must legally pass
- A specific programming language built only for cloud applications
- A tool that automatically writes a complete twelve-part application for you somehow
Which is one of the twelve-factor principles mentioned here?
- Keep configuration in the environment rather than hard-coded in the app
- Hard-code every setting and secret directly into the source code
- Make the development and production environments wildly different
- Have the app carefully manage and store all of its own log files internally
Why does the topic say a bigger version number doesn't simply mean "better"?
- A MAJOR bump can signal a breaking change, not necessarily an improvement
- Because version numbers count downward as the software gets better
- Because the version number is really a measure of how fast it runs
- Because version numbers are assigned completely and utterly at random each time
You got correct