DEV Community

Cover image for 0.58.0 and v0.58.0 Are the Same Version. Our Code Disagreed.
Nabil A
Nabil A

Posted on AI-assisted

0.58.0 and v0.58.0 Are the Same Version. Our Code Disagreed.

On Nov 18 I asked our own API a simple question: what changed in golang.org/x/net since 0.58.0?

It told me the package wasn't in the catalog.

It was. We had every release of it. We just had them stored as v0.58.0, with a v, because that's how the Go module proxy writes them. I had typed it without the v, the way plenty of people type it in issues, in chat, and apparently in my own head.

That one answer turned into a day of finding every place in our code that compared versions as plain text. There were a lot of them.

1. The bug looked like a typo

Since tracks what code depends on (packages, AI models, APIs, runtimes) and tells people and their coding agents what changed. So "what changed since version X" is the question we answer more than any other. And version X shows up in whatever spelling the asker's tools happen to use.

Here's the whole problem in a few lines. Each pair is the same version, as two real tools write it:

const pairs = [
  ["0.58.0", "v0.58.0"], // a Go module, with and without its v
  ["2.31", "2.31.0"],    // a requirements.txt pin and the PyPI release
  ["v18.2.0", "18.2.0"], // a manifest and the npm release
  ["go1.20", "1.20"],    // how Go's own tools write Go 1.20
  ["1.8", "8"],          // Java, before Java 9 renumbered itself
];
for (const [a, b] of pairs) console.log(a.padEnd(8), b.padEnd(8), a === b);
Enter fullscreen mode Exit fullscreen mode

Run with Node 24 in an empty folder, it prints:

0.58.0   v0.58.0  false
2.31     2.31.0   false
v18.2.0  18.2.0   false
go1.20   1.20     false
1.8      8        false
Enter fullscreen mode Exit fullscreen mode

Five pairs, five false. Every one of them is the same version to the person who wrote it.

2. Each place had already met one spelling

The embarrassing part wasn't the bug. It was what we found when we went looking for it.

Different parts of the codebase had each run into one spelling at some point and patched for it right there. The Go v had been added back by hand in six different files. A short 13.0 was written out to 13.0.0 in one place. Everywhere else, a version that wasn't spelled exactly like the stored one just didn't match.

So the answer you got depended on which door your version came in through:

  • A requirements.txt pin of ==2.31 never met PyPI's 2.31.0.
  • A manifest that said v18.2.0 never met npm's 18.2.0.
  • Asking about go1.20, which is how Go's own toolchain writes it, got back "may be on 1.20; the declaration could not be read", for a Go release line that ended in 2024.
  • Java 1.8, which is how a Gradle build writes Java 8 (JavaVersion.VERSION_1_8), met no release line at all.

That last one deserves a footnote. Java called itself 1.2, 1.3, all the way to 1.8, and then Java 9 dropped the "1." for good. So every tool that's been around long enough still writes Java 8 as 1.8, and every list of release lines calls it 8. Both are right. They just never meet.

Nothing crashed. That's what made it bad. A version that didn't match didn't throw an error, it quietly got a smaller answer, and a smaller answer looks exactly like a correct one.

3. The number that made it not a typo

The worst one was in security advisories for Go.

Of the 12,714 Go advisories we had stored, 10,337 carried the advisory database's spelling of a version, like 0.62.0, next to the Go proxy's v0.62.0. Our answers and our fix emails printed the advisory's spelling.

Go's tools want the v. Paste go get golang.org/x/net@0.62.0 and Go refuses it. So for about 81% of Go advisories, the "upgrade to" version we showed was one you couldn't paste.

At that point it stops being an edge case. It's the main case, wearing an edge case costume.

4. The fix we almost wrote

The obvious fix was a seventh patch: add the v back in one more place, ship it, go to lunch.

I'd already seen where that road goes. It goes to six files, each with its own little opinion about what a version looks like, each one right about the one spelling it had met and wrong about the rest.

So we did it once instead. Each registry gets one rule for what "the same version" means, written the way that registry's own tools read a version:

  • Go: with or without the v.
  • PyPI: 2.31 is 2.31.0, padded and normalized the way Python's own version rules (PEP 440) say.
  • npm: a leading v is dropped.
  • Maven: qualifiers in any case, so 31.1-JRE is 31.1-jre.
  • Runtimes: each one's own tool prefix (go1.20, python3.9, node18, net8.0), and Java's numbering before 9, so 1.8, 1.8.0_292 and 1_8 are all Java 8.

Then every place that takes a version from the outside world (a question, a manifest, a lockfile, an advisory) asks that one rule before it compares anything. The six local patches got deleted, which was the most satisfying diff of the week.

5. Where "the same" is a trap

The part I'm actually proudest of is what we refused to merge.

Some places really do treat two spellings as two different things. A Docker tag or a GitHub Actions ref is the same only when it's written the same: a tag named v4 and one named 4 can point at completely different things. So there, text comparison stays. A "smart" normalizer that stripped every v everywhere would have been a brand new bug with a nice commit message.

Then the same disease showed up somewhere I didn't expect: type signatures.

We read the code of package releases, so we can tell you when a function you call changed shape. That diff compared signatures as text. So in Python, List[str] and list[str] counted as a breaking change. So did Optional[bytes] and bytes | None. In TypeScript, Array<string> and string[]. In Go, interface{} and any.

We measured it on production data, read only. Of the stored code-only signature changes, these were nothing but respellings:

Registry Respellings Of stored signature changes
PyPI 26,823 159,772
npm 2,467 125,044
Packagist 1,620 21,503
Go 190 5,489
crates.io 14 16,362

One in six PyPI "signature changes" was Python learning to write list in lowercase.

Same fix, same caution. Compare what the language itself says is one type, and nothing more. TypeScript's ?: T and ?: T | undefined stay different, because TypeScript treats them differently. A parameter's name stays part of it wherever callers can pass it by name.

And one more, because it made me laugh: Guava ships most releases twice, as -android and -jre. We were reading the difference between the two flavors of the same release as changes. That was 88 of Guava's 100 newest steps. A version now stays on its own flavor's line.

6. What changed for anyone asking

Since Nov 18 this is live. You can ask the way your tools write it and get the same answer as the registry's own spelling:

  • Versions: 0.58.0 or v0.58.0 for a Go module, 2.31 for PyPI's 2.31.0, v18.2.0 on npm, 31.1-JRE on Maven.
  • Runtimes: go1.20 is Go 1.20, Java 1.8 is Java 8.
  • Names: crates:serde-json (crates.io reads - and _ as one), docker:node, node@18, golang@1.20.

I checked this morning (Nov 19). Asking what changed in golang.org/x/net since 0.58.0 now answers from v0.58.0: five releases behind the latest, v0.63.0. And go1.20 comes back as Go 1.20, end of life Feb 6, 2024.

What I'd tell myself before

When you catch yourself writing the same small fix in a second place, the spelling isn't the bug. The bug is that nobody owns the question "are these two the same?" Give that question one owner, send every input through it, and be exactly as careful about what it must never merge as about what it should.


What's the strangest version string a tool has ever insisted on in your codebase?

I'm Nabil. I build Since, which tracks what your code depends on and tells you before it breaks.

Top comments (0)