Skip to content

Update README with guidance on version updates #1979

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 5 commits into from
Closed

Update README with guidance on version updates #1979

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3592726
versions bump
lalitb Jul 30, 2024
b08f034
Fix
lalitb Jul 30, 2024
7f3e433
breaking changes with minor version update
lalitb Jul 31, 2024
d1b1a78
update
lalitb Jul 31, 2024
44b05f8
Merge branch 'main' into version-updates
lalitb Jul 31, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,12 @@ See the [examples](./examples) directory for different integration patterns.

## Overview of crates

The following crates are maintained in this repo:
OpenTelemetry Rust is composed of multiple interdependent crates as given below,
each of which may have different version numbers. To maintain compatibility
and ensure proper functionality, it is recommended to update all related
crates simultaneously when new versions are released. Although it would be
ideal to avoid breaking changes with minor version updates, this is currently
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This makes it sound like are we are required to avoid such breaking changes, but we would not be able to do it. It's completely valid under Semver compatibility rules to make breaking changes with minor version updates for 0.x.x versions.

If the intention is to warn users who might have misconception about what kind of breaking changes are allowed, maybe we could just reiterate the relevant Semver compatibility rule. Something similar to the text in this doc:

Versions are considered compatible if their left-most non-zero major/minor/patch component is the same. For example, 0.1.0 and 0.1.2 are compatible, but 0.1.0 and 0.2.0 are not.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's completely valid under Semver compatibility rules to make breaking changes with minor version updates for 0.x.x versions.

This is what I read from semver:

MAJOR version when you make incompatible API changes
MINOR version when you add functionality in a backward compatible manner
PATCH version when you make backward compatible bug fixes

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh you mean with 0 as major version.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The issue I observe is that in the Rust ecosystem, most of crates are in 0.x.x versions but are considered stable, with minimal breaking changes occurring with minor version updates. I just wanted to emphasize that for OpenTelemetry, this would be comparatively more frequent.

Copy link
Contributor

@utpilla utpilla Jul 31, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Got it. Thanks for providing the context! Maybe we can put this text under its own section in the doc to highlight this point even more? Something like this: https://github.com/rust-random/rand?tab=readme-ov-file#versions

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am unsure what is the issue we are trying to address with this wording? Can you elaborate.
Is it to convey that we are not stable?
Is it to convey that breaking changes are possible within minor version bump, until a crate hits 1.0?
Or more?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am unsure what is the issue we are trying to address with this wording? Can you elaborate.
Is it to convey that we are not stable?
Is it to convey that breaking changes are possible within minor version bump, until a crate hits 1.0?
Or more?

Maybe I haven't put the wordings properly. The main emphasis was this

To maintain compatibility and ensure proper functionality, it is recommended to update all related
crates simultaneously when new versions are released.

i.e., to ask users to update to the latest versions of all OpenTelemetry crates together when new releases are made. Additionally, if there are any indirect dependencies on OpenTelemetry crates (e.g. such as those coming through tracing-opentelemetry), they should ensure that the versions are same (preferably latest). If not, reach out to the repo providing this dependency asking them to update.

But looks like the PR is causing more confusion, and less value. Would be good to close this :)

not feasible until all signals within the ecosystem reach stability.

* [`opentelemetry`] This is the OpenTelemetry API crate, and is the crate
required to instrument libraries and applications. It contains Context API,
Expand Down
Loading