Release names and version codenames: when a release needs a name (and when it doesn’t)

Somewhere between “v2.4.1” and “macOS Sequoia” there is a decision most teams never make deliberately: does this release get a name? Version numbers and release names do different jobs. A number is a compatibility statement — it tells a machine, or a careful human, what upgrading will cost. A name is a communication device — it tells a story, marks a moment, and gives people something they can actually say out loud. Most releases only need the first. Some genuinely benefit from the second. And a naming scheme adopted casually becomes a treadmill you’re still walking years later, in public.

This guide is about when names earn their keep, what the famous schemes got right and wrong, and the changelog mechanics that keep a named release findable three years later — because “fixed in Ocelot” is a useless line in a bug tracker once nobody remembers which number Ocelot was.

What a name does that a number can’t

Names have four legitimate jobs. If your release does none of these, it doesn’t need one.

  • Making a release an event. “Version 14” is an increment; “Sequoia” is a launch. Products with one or two marketing-grade releases a year — the tier-one launches from the feature announcement guide — use a name to bundle a hundred small changes into a single thing the press can write about and users can anticipate. This only works at low frequency: if every release has a name, no release is an event.
  • Being speakable. Humans in support threads, sales calls, and hallway conversations are bad at remembering whether the problem appeared in 10.2 or 10.3, and surprisingly good at remembering it was “the Jaguar one.” A name is a mnemonic handle for people who don’t live in your version history.
  • Talking about unreleased work. An internal codename decouples conversation from commitment. Your team can plan “Project Cedar” for months before deciding whether it ships as 3.0 or 2.8 — the codename absorbs scope changes that would make a promised version number a lie. This is the one job where the name comes first and the number is assigned late.
  • Ordering without arithmetic. Alphabetical schemes — Ubuntu’s adjective-animal pairs, Android’s desserts — let anyone sort releases without knowing the numbers: Jammy comes after Focal because J comes after F. It’s a genuinely clever trick, and it’s also a constraint you’ve signed up to satisfy forever (and an alphabet only has 26 letters before the wrap-around gets confusing).

What the famous schemes teach

Ubuntu is the best-engineered scheme in the industry, because the name never works alone: every release is an alliterative adjective-animal pair and a CalVer number — 24.04 is Noble Numbat, and the number tells you it shipped in April 2024 while the letter tells you where it sits in sequence. Name for humans, number for machines, both on every surface. Nobody is ever stranded knowing only the name.

Android is the cautionary tale about audience. The dessert names (Cupcake through Pie) were alphabetical, charming, and — Google concluded after a decade — not globally legible: not every culture knows what a marshmallow is, and new users had no idea whether KitKat came before or after Lollipop. In 2019 the public branding retired the desserts for plain numbers (“Android 10”), while the codenames survive internally. The lesson isn’t “names fail”; it’s that a name’s job is communication, and a name your actual audience can’t decode is decoration.

Windows shows what scheme incoherence costs: 95, 98, ME, XP, Vista, 7, 8, 10 — years, letters, words, and numbers with no consistent ordering signal (is Vista before or after 7? you just have to know). Every scheme change spends the one thing a scheme exists to provide: instant, thoughtless ordering. Debian shows a scheme wearing in rather than out: Toy Story characters since the 90s, with the permanently-unstable branch permanently named Sid, the kid who breaks toys — the joke is load-bearing documentation. And the Linux kernel shows that a name nobody uses is harmless: every kernel has a codename (“Baby Opossum Posse”), nobody ships, reports, or discusses kernels by it, and that’s fine — the number does all the work, and the name is a maintainer’s private amusement.

The iron rule: the number stays canonical

Whatever you name a release, the name is an alias. The version number remains the identifier everywhere state is kept: the changelog entry, the bug tracker, the API version header, the package registry, the support macro, the feeds and machine-readable surfaces. Machines don’t know that 4.0 is “Emerald Falcon,” and neither does the engineer reading a three-year-old issue that says only “broken since Falcon.”

The operational form of the rule: any surface that shows the name shows the number beside it, at least once. “v14 (Sonoma)” in the changelog title; “Sequoia (macOS 15)” in the marketing post; a versions table somewhere permanent that maps every name to its number and date. The inverse is not required — numbers may appear alone anywhere — which is exactly what makes the number canonical and the name optional. If dropping the name from a surface loses information, your naming scheme has quietly become a second, competing version scheme, and you’ll pay for it in every conversation that has to reconcile the two.

Codename hygiene: when internal names go public

Internal codenames leak. They leak in commit messages, conference talks, job postings, and accidentally-public roadmap slides — so the first rule is to pick codenames that are safe to leak: no customer names, no competitor jokes, nothing you’d wince at on the front page of a tech-news aggregator, and a quick check that the word isn’t rude or unfortunate in the languages your users speak. A themed pool of neutral words (rivers, birds, typefaces) decided once beats a clever one-off decided at midnight.

The second rule is that codenames retire at release. The moment Project Cedar ships as v3.0, the changelog entry says so — one line, “previously referred to as Cedar” — and from then on every document says v3.0. The failure mode this prevents is the bilingual docs problem: half your internal tickets, and worse, half your public forum threads, referring to Cedar while the release notes say 3.0, with no written mapping anywhere. One mapping line in a permanent, linkable archive costs nothing and settles every future argument about what shipped when, under what name.

When a release should just be a number

  • Continuous-delivery SaaS. If you ship daily, you don’t have releases in the marketing sense — you have a dated stream, and dates are better names than names are. Naming a Tuesday deploy “Osprey” adds ceremony to something whose whole virtue is routine.
  • Libraries and developer tools. Your audience reads release notes at upgrade time inside a dependency-bump diff. They need the semver signal, not a theme. (The kernel exception proves the rule: the name exists, and correctly, nobody uses it.)
  • Anything whose primary reader is a machine. Dependency bots, CI scripts, and vendor-monitoring dashboards compare versions. A name in the version field breaks sorting; a name next to it is noise they skip.

And one distinction worth stating because search traffic confuses them: naming a release is not renaming the product. If the thing formerly called Taskboard is now called Flow, that’s a product rename — a trust event with its own playbook — not a version codename, and dressing it up as one (“introducing Flow, the new Taskboard 5.0”) muddies both.

Changelog mechanics for named releases

The announcement entry carries both identifiers in the title — “v14 (Sonoma): faster search, redesigned editor” — because the title is what feeds, link previews, and search results show, and both audiences (the human who knows the name, the operator who knows the number) need to find it. After the announcement, subsequent entries go number-first: patch notes for “14.0.2”, not “Sonoma hotfix 2.”

Two register warnings. Security advisories use numbers only — an advisory’s job is precise version-range identification, and a playful codename in that context reads as unseriousness exactly where seriousness is the product. Same logic, softer form, for tone generally: the name is a marketing register, and it belongs on marketing surfaces.

Anti-patterns

  • The name-only announcement. A launch post that never states the version number. Every future reference to the release now requires a lookup that the announcement could have settled in four characters.
  • Abandoning the scheme mid-alphabet. Skipping a letter, or quietly stopping, converts the scheme’s one asset — predictable order — into a trivia question. If the scheme has become a burden, end it explicitly in a changelog entry, Android-style, and go to numbers.
  • Codename drift. Docs, tickets, and forum answers using the codename after release while official surfaces use the number, with no published mapping. Your search index now has two disjoint bodies of knowledge about one release.
  • Joke names on serious releases. The release that patches a critical CVE is not the moment for “Grumpy Gremlin” to headline. The number leads; the name sits this one out.
  • Unsortable names as identifiers. If support asks users “which version?” and the answers come back as non-alphabetical names (“Aurora”? “Zephyr”? which is newer?), the scheme is generating lookups instead of preventing them. Either the names order themselves or they never appear without the number.
  • A name per sprint. Naming everything means nothing is an event, and the pool of good words runs dry by summer. Names are a budget, like humor: spend them on releases that are genuinely occasions.

How this works in Wakelog

Release naming in Wakelog is a writing convention, not a feature — which is the honest way to say you don’t need tooling for it. Put both identifiers in the entry title (“v14 (Sonoma): …”) and the public page’s search finds the release by either one. The entry’s permalink is the stable mapping line you can cite in tickets and forum answers for years. Tag the announcement entry announcement so the ?tag= filter doubles as a table of your named releases, newest first — and your feeds carry the same titles, so subscribers see the name and the number together, which is the iron rule doing its job automatically.

Create a free changelog and the naming decision stays exactly as big as it should be: one line in a title, not a feature you configure.

Related guides

Last updated 2026-08-01 · All guides