Our JavaScript SDK is published to npm by a release workflow that runs whenever a version tag is pushed. In April we began version 4, which changed how authentication is configured, and pushed a tag for 4.0.0-beta.1 so that three customers could try it early.
The workflow ran npm publish, as it always had. npm attaches a dist-tag to everything it publishes, and unless told otherwise that tag is latest, whether the version is stable or a prerelease. Latest is what anyone gets from npm install with no version, and what the package page shows. For five days, every new project that added our SDK got a beta whose configuration matched none of the examples in our documentation.
Existing customers were fine, which is why it took five days to notice. Their package.json files held ranges like ^3.4.0, which never reach version 4, so their installs and updates stayed where they were. Only fresh installations followed latest. Support saw a handful of tickets about an options object that did not exist, from developers who were following the docs exactly, and assumed they were not.
Within minutes of understanding it we pointed latest back at 3.4.2 with npm dist-tag add, and wrote to the developers we could identify. The release workflow now works out the dist-tag from the version itself: anything with a prerelease part is published under next, and the job refuses to publish a prerelease without an explicit tag rather than trusting npm's default. After publishing, it reads the dist-tags back from the registry and fails if latest is not the highest stable version. The publishing token can only be used by that workflow, so nobody can repeat this from a laptop. And every page of our documentation states the SDK version it was written for, so a developer looking at code that does not match can see why.
A registry has opinions about what a release means, and they live in its defaults. Ours assumed that the newest thing we pushed was the thing everyone should have, and we had never told it otherwise because until that day it had always been true.
– Sergey Shinder
Top comments (0)