Planned SDK 2.0 Release (Important Dates and Information)

[pichlermarc]

Description

Important

This is not an official announcement yet.
This issue is in refinement stage - we may still change parts of the plan as we continue working out the details.

Quick Summary

We're planning to release a 2.0 version of stable SDK packages. This release will include breaking changes that aim to make the stable SDK packages easier to maintain and use - which will improve development velocity in the long run.

We plan to feature-freeze 1.x and 0.x on Dec 14 2024, any feature PRs merged later than that will target SDK 2.0.
We plan to release SDK 2.0 on Feb 17 2025 - between feature-freeze and SDK 2.0 release 1.x and 0.x packages will only receive bugfix releases.

Why we're bumping the SDK to 2.0

The 1.x SDK release supports Node.js versions that are out-of-date, such as Node.js v14. As more and more of our dependencies and devDependencies drop support for this Node.js version we amass more and more technical debt. It forces us to develop workarounds which take lots of time to maintain - this takes time away from feature development and is not sustainable long-term. Dropping support for Node versions is a breaking change and therefore requires us to bump the major version of our packages.

Similar to the outdated Node.js versions, we also support TypeScript >4.4, which limits us in which tools and language features we can use. Bumping TypeScript will cause our type-output to change and may break users that also use older TypeScript versions. Therefore this change requires us to bump the major version.

We have identified problems with our current exports. We usually export TypeScript classes, which, in the context of a library means that we expose private fields as part of the public API. This makes it extremely difficult to innovate as every small change is potentially breaking for our users. We also export some types that were unintentionally exported. Removing these types from the public API is a breaking change. It does, however, make it easier to make internal changes and reduces the risk for unintentional breaking changes for end-users.

We currently do not specify a minimum supported browser version this means that we have to deal with bugs that only occur on very old, and long-out-of-support browsers. Removing this support is a breaking change, but by dropping support for these old versions, we free up bandwidth to work on other things.

Some features are difficult for end-users to understand due to the way they are implemented and it is possible to do things in an incorrect order. However, in many cases we cannot change the public interface to make it easier to use without introducing a breaking change. In SDK 2.0 we aim to iron out some of these issues and make the SDK easier to use in these areas.

How (and when) we're moving forward

Important

@opentelemetry/api follows a different versioning scheme and is NOT included in the SDK 2.0 efforts and will therefore not receive any breaking changes. No pull-requests for breaking changes targeting the @opentelemetry/api package will be accepted.

Currently development for SDK 2.0 takes place on the next branch. There we stage these changes to ensure that feature development can continue for the time being. Maintainers periodically merge changes from main to next to ensure features and bugfixes are kept in sync.

On Dec 14 2024 we will enter feature-freeze for 1.x. From this point onward:

• only bugfixes will be accepted for 1.x
• any unmerged features will only be accepted for 2.0, users may have to rebase their PRs to ensure that they remain mergable

On Feb 17 2025 we will release 2.0.

In the time from Dec 14 2024 to Feb 17 2025

• we may accept breaking changes to the SDK and other packages as long as these changes loosely follow the goals set out in the above sections and follow the specification.
• we will not release any new features, but we will still accept feature PRs to the 2.0 branch
• we will back-port and release bugfixes for the state that entered feature-freeze on Dec 14 2024 (the 1.x and 0.x line of packages)
• contrib development will continue as-usual

What this means for you

End-Users

You will still receive bugfixes, but new features merged after Dec 14 2024 will only be released on Feb 17 2025.

There will be no breaking changes in @opentelemetry/api as it follows a different versioning scheme and has different stability guarantees then the SDK 2.0 packages. Any code written against @opentelemetry/api should continue to work as usual. You may have to update to the latest feature version of @opentelemetry/api to keep compatible with SDK 2.0 packages.

Upon release you may have to adjust your SDK setup code to the new interface. To prepare for this, we recommend you periodically update @opentelemetry/* packages to the latest version, and if you are using interfaces that are marked as @deprecated we recommend you take the transition path outlined for that feature.

Instrumentation authors

@opentelemetry/instrumentation may receive breaking changes, so you may have to update your instrumentation upon release to keep compatible with newer releases of the package. However, you will still be able to register your instrumentation with an older versions of @opentelemetry/instrumentation

@opentelemetry/api WILL NOT receive breaking changes. Your actual instrumentation code (writing metrics, traces, interacting with context and propagation) using @opentelemetry/api should remain the same even when SDK 2.0 is released.

If you're using any other @opentelemetry/* packages, please ensure that you're not using any deprecated features. You may still have to adjust some of your code to the new interface upon SDK 2.0 release. If you SDK components in testing, you may have to adjust tests when upgrading to SDK 2.0.

Thrid-party distributors of OpenTelemetry JavaScript SDKs

If you're a third-party distributor of OpenTelemetry JavaScript SDKs you should follow the same steps as outlined in the End-User section. Upon release, you may have to update your distribution's code to adjust to the new public interface of the OpenTelemetry JavaScript SDK. Depending on if your distribution exposes/accepts SDK 1.x types or not, this may also require you to bump the major version of your distribution.

If you implement a thrid-party SDK based on @opentelemetry/api, the planned changes in the SDK do not affect you.

[dyladan]

In the time from Dec 14 2024 to Feb 17 2025
...
we will not release any new features

We will not release new features, but we will still accept feature PRs to the 2.0 branch I think correct?