Release v1.0.0 stable version of common #771
Comments
I lack experience personally with having an
I'd like for the |
|
I don't think an We already do have good practices around breaking changes. For example with There is no preventing change. We must move our codebases forward. We can do our best to review changes to make sure interfaces are stable and well designed. But mistakes happen, design patterns change, and we need to publish a breaking change. I don't think we need or want a 1.0 of this library.How would this actually work? What's the day-2 plan? Would we keep IMO we don't have the people-time to maintain several release branches over any time in order to support older major versions. We barely do this (LTS) for prometheus itself. I also think this will just churn the major version of the module for no utility. And that's going to be even more painful for us, as well as downstream users. Also, how do you define breaking? Just function signatures? Structs? Just function removals? There are lots of small things that could be breaking or deprecated. Any behavior change comes with concequences. I think we need to improve our design and review quality.Easy to say, hard to do. But that's where I'm at with what are the realistic ways we can improve the quality of life for downstream users of our code. Similar to how Linux has a "don't break userspace" creed, I think we need to consider our downstream users more when making changes. |
|
Nice writeup @SuperQ :) |
@SuperQ @bwplotka Is there anything concrete we can do in this regard? As a concrete example, I think actually the |
Perhaps we shouldn't have it in common. We could/should reduce the friction to creating new repos for Go libraries that don't need to be in The definition in the README.md is this:
If a library is meant for external use, perhaps it needs to be split out. |
That's a good point. @ArthurSens WDYT? |
|
I'm not sure if Bartek created this issue just because of Regarding releasing Common 1.0, I generally agree with what Ben mentions above. The problem I'm seeing here in this repo is that it does way too many things, and we have way too few hands to maintain such a generic codebase. Some things are not that important and will need a 1.0 release with all the complicated stability guarantees, but other parts have so much adoption that changing any part of it will break dozens of downstream projects. It would make sense to create a separate repository and assign maintainers who show expertise in the most adopted parts of the codebase. I can take ownership of |
|
@bwplotka Should we require CI checks and reviews before being able to merge a PR? I notice they are currently not required. |
Agree. Maybe we should offer a template Go repo so it's easier to create those. Also automation to release it (go releases, our CI GH actions propagation etc).
Let's talk about this more. (: One could argue that this is no longer true ("considered internal to Prometheus"). There are pieces that leaks to external use, e.g.:
It's just not possible to stop users from using useful common utilities outside of Prometheus 🙃 Second argument/question is.. should stable module depend on unstable module? How can we ensure stability if dependency can break anytime? Doesn't go mod tooling punish quite much deps with indirect deps that have breaking changes? It's ok for binaries maybe, but is it ok for libraries like client_golang?
What do you do with Prometheus 1.x version? You keep it, don't support it. That's ok and enough. Let's give option for people to control when they have time to make manual changes to their code, not wake downstream users in random moments because common hiddently broke 4 layers down the upgrade for irrelevant pieces of code.
Yes. But equally we don't have people-time to deal with the common upgrade breaking other people code the moment they upgrade client_golang (e.g. https://github.com/prometheus/client_golang/releases/tag/v1.21.0) which suppose to be stable. It just feels like a ticking bomb.
All of the above like client_golang is enduring for years, with all it's glory and flaming feedback when we break people by mistake 🙃 (or intentionally - sometimes you do break but you make it clear and loud, and you give mitigation plans). |
|
One alternative is for client_golang to stop depending on prometheus/common which might be the desired outcome here. We could vendor what we need if API stability is not on the roadmap for this module. I definitely agree common has so many different packages with variety of stability needs. |
|
If anyone is interested on why stability of Go libs is essential, feel free to read a short story from @dims on k8s channel: https://kubernetes.slack.com/archives/CHGFYJVAN/p1741621071818569 |
|
Just linking another argument for v1. By chained dependency, stable Otel Go SDK depends on stable client_golang which depends on unstable common which causes some deprecation risks. |
Hi 👋🏽
It's time to take common to a higher stability level. We damage the ecosystem by making breaking changes (I authored some 🙃 ) e.g. thanos-io/thanos#8162 (pulling some dep suddenly break another dep etc.).
If we need more data on how much problematic 0.x common version is, to motivate this, I can try to research exact numbers, let me know!
cc @aknuds1 @SuperQ
The text was updated successfully, but these errors were encountered: