v1.0.0-rc.1 Post Mortem

[dyladan]

What happened?

Around 2:30 PM EST on Tue May 18, we pushed API version 1.0.0-rc.1 which contained breaking changes which were incompatible with 1.0.0-rc.0. Many users, including anyone using the default SDK, depended on the "carat" range ^1.0.0-rc.0 which allowed the upgrade to 1.0.0-rc.1 automatically.

This issue was resolved around 8:00 AM EST on Wed May 19 by pushing a reverted version as 1.0.0-rc.2. For specific mitigation steps, see "What did we do to fix it," below.

What was the impact?

The broken 1.0.0-rc.1 version was downloaded 184 times before it was deprecated on NPM. There is no way to know who these 184 downloads were. Many of them were CI builds, but it is likely that at least some "real" users installed the broken package.

How did this happen?

This was caused by a misunderstanding of the way that semver handles prerelease packages. We were under the mistaken impression that users who depended on "carat" ranges would not receive the next prerelease version without specifically installing it.

To quote the semver documentation:

^1.2.3-beta.2 := >=1.2.3-beta.2 <2.0.0-0 Note that prereleases in the 1.2.3 version will be allowed, if they are greater than or equal to beta.2. So, 1.2.3-beta.4 would be allowed, but 1.2.4-beta.2 would not, because it is a prerelease of a different [major, minor, patch] tuple.

What did we do to fix it?

As JavaScript maintainers, we took the following steps:

1. Release 1.0.0-rc.0 as 1.0.0-rc.2, reverting all changes introduced by 1.0.0-rc.1 for users who depended on ^1.0.0-rc.0 or ~1.0.0-rc.0.
2. Deprecate 1.0.0-rc.1 on NPM

What is the plan moving forward?

1. The code which was released as 1.0.0-rc.1, which contains important fixes and updates, will be released as 0.19.0.
2. Until we release a GA 1.0.0 version, we will stay at 0.x.y, which allows us to push breaking changes as minor version bumps.
3. After 1.0.0 there will be no breaking changes released.

[nirsky]

I may be stating the obvious, but I found this tool online, could be useful to validate semver in the future: online semver checker

[dyladan]

I may be stating the obvious, but I found this tool online, could be useful to validate semver in the future: online semver checker

Yeah I've seen this tool before. The problem with thinking you understand something is that it doesn't occur to you that you should double check it 💀.

In the future, we're not going to use semver prerelease tags at all.

[dyladan]

This issue will be pinned for 1 week, then will be closed.

[aabmass]

• The code which was released as 1.0.0-rc.1, which contains important fixes and updates, will be released as 0.19.0.
• Until we release a GA 1.0.0 version, we will stay at 0.x.y, which allows us to push breaking changes as minor version bumps.

@dyladan a lot of the packages in the opentelemetry-js repo have a peer dependency on @opentelemetry-api ^1.0.0-rc0 still, which makes them conflict with the 0.19.0 release. What's the plan with those? I could see a few options:

• pin them to 1.0.0-rc.3 without a carat
• downgrade the dependency to "^0.19.0"

[dyladan]

They will be "downgraded" to 0.19.0, which is actually newer code than 1.0.0-rc.0

[aabmass]

Any estimate on when to expect that release ?

[Flarna]

I think we should in general avoid to release a new, breaking API version marked with latest on NPM before the corresponding core and contrib modules are in place.
There are a lot issues created meanwhile just because people use latest of all components but they don't fit.

[dyladan]

We could release with @next tag on NPM which would mean an npm install @opentelemetry/api would receive the previous version (npm install gets @latest by default), but we would have a published version to make core/contrib changes against.

@next is different than including it in the version. It would still be a minor version increase.