[docs, .github] Add new issue template for stabilizing a module #8935
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #8935 +/- ##
==========================================
- Coverage 90.87% 90.82% -0.05%
==========================================
Files 317 318 +1
Lines 17225 17205 -20
==========================================
- Hits 15653 15627 -26
- Misses 1281 1284 +3
- Partials 291 294 +3 ☔ View full report in Codecov by Sentry. |
| - [ ] No open issues or PRs in the module that would require breaking changes | ||
| - [ ] No TODOs in the module code that would require breaking changes | ||
| - [ ] No deprecated symbols in the module | ||
| - [ ] No symbols marked as experimental in the module |
There was a problem hiding this comment.
Curious why? Seems common for stable module to have experimental APIs, e.g. grpc-go.
There was a problem hiding this comment.
We discussed a bit about this on #4705 and #4832. Personally, I think grpc-go's approach has caused a lot of pain to end-users; I gathered some issues related to it on #4832 (comment).
We also have the experience of opentelemetry-go, where their decision to have interfaces that can change across minor versions has caused some pain (see open-telemetry/opentelemetry-go/issues/3277)
We can discuss this more explicitly (I think having a more explicit guideline as to how to implement experimental methods is important), but for now I think requiring the 1.0 version to not have experimental symbols is not too onerous
There was a problem hiding this comment.
Thanks for the context, I agree the implication of experimental APIs can be a separate discussion. Makes sense to me to not have them for 1.0 to begin with (since relaxing this constraint in the future is feasible).
|
|
||
| Before stabilizing a module, an approver or maintainer must make sure that the following criteria are met: | ||
|
|
||
| - [ ] One RC release or more have been done of this module |
There was a problem hiding this comment.
Do we want to do rc releases going forward, given the reported issues?
There was a problem hiding this comment.
I think doing one or two RC releases makes sense, but I agree that definitely 18 RC releases is too much 😄 We can add some guidance to this document as part of solving #8063 (something like "if we do more than two RCs go back to minor versions until we solve the issue(s) in question")
There was a problem hiding this comment.
Maybe we can just require two 0.x versions with all other checkboxes marked instead of jumping back and forth to RC
There was a problem hiding this comment.
unless there's a strong argument for a RC tag, i would agree that we could call a package out as RC as of version 0.x and avoid unnecessary process and pain
|
Overall LGTM. Thanks for putting this together! |
|
Accidentally re-requested Alex's review, feel free to ignore :) |
Clarifies our stance regarding RC releases, inspired by #8935 (comment). In a nutshell: - Stabilization criteria have to be met for at least two minor version releases before moving to the stable module. - We treat these two (or more) minor releases as release candidates and do not release under the `-rc` release family. - After these releases, we move directly to the `1.x` release family. **Link to tracking Issue:** Fixes #8063 (together with the upcoming 1.0 release for pdata and featuregate) cc @braydonk --------- Co-authored-by: Anthony Mirabella <a9@aneurysm9.com>
…-telemetry#8935) This adds a new release template for stabilizing a module. The intent is to try this out for pdata and featuregate, and iterate on the template over time.
Clarifies our stance regarding RC releases, inspired by open-telemetry#8935 (comment). In a nutshell: - Stabilization criteria have to be met for at least two minor version releases before moving to the stable module. - We treat these two (or more) minor releases as release candidates and do not release under the `-rc` release family. - After these releases, we move directly to the `1.x` release family. **Link to tracking Issue:** Fixes open-telemetry#8063 (together with the upcoming 1.0 release for pdata and featuregate) cc @braydonk --------- Co-authored-by: Anthony Mirabella <a9@aneurysm9.com>
Description:
This adds a new release template for stabilizing a module.
The intent is to try this out for pdata and featuregate, and iterate on the template over time.