Release notes are not mentioning breaking changes

[jonatan-ivanov]

There were a bunch of breaking changes in opentelemetry-java-instrumentation:1.28.0 (e.g.: #8738) but according to the release notes there were no breaking changes.

Could you add some automation around release notes generation so that people will be aware that there are breaking changes in that release and also can find the migration path (usually in the PR that introduced the breaking change)?

See original thread on Slack: https://cloud-native.slack.com/archives/C014L2KCTE3/p1689965360046879

[jaydeluca]

We do document breaking changes in release notes, for example:

[jonatan-ivanov]

I think in the description of this PR there is a counter example.

[jaydeluca]

@jonatan-ivanov yes, but that is from 2023, and the one I mentioned is from after that. Do you have other examples that indicate this is a systemic problem? We always want to provide a best effort at document breaking changes, and I'm sure that any that have been missed were not intentional.

[jonatan-ivanov]

but that is from 2023

This issue is also from 2023. 🙂 Btw, the release notes that the issue mentions is still not fixed (I also reported it on Slack, maintainers did respond on the thread).

Do you have other examples that indicate this is a systemic problem?

This was not a one off. Around that time, it happened quite a few times (also reported that on Slack) but now since the APIs we used got stabilized, I will not notice them.

We always want to provide a best effort at document breaking changes

I understand, I think that's why there are things that are missing. This issue was created based on the linked Slack thread, one of the maintainers asked me to create it so that some automation around release notes generation can be added so that people will be aware that there are breaking changes in that release and also can find the migration path (usually in the PR that introduced the breaking change). Pointing out an example where breaking changes were called out not sure invalidates the issue, it's more about automation. I think adding a label to issues/PRs that introduce breaking changes and call those out separately on the release notes would help a lot.

and I'm sure that any that have been missed were not intentional

Me too, not fixing them after they were reported might have been though.

[jaydeluca]

what do you think of what I propose in #14785 ?

[jonatan-ivanov]

This is awesome, thank you very much!

[trask]

and I'm sure that any that have been missed were not intentional

Me too, not fixing them after they were reported might have been though.

@jonatan-ivanov this comment is unnecessary. this is an open source project. PRs are welcome.

[jonatan-ivanov]

I think I was talking about the content of the already created GitHub releases. Contributors can create PRs to fix release note generation for future releases like #14785 but contributors cannot really create a PR for editing existing release notes I guess.

[trask]

You can PR against the CHANGELOG.md