nim-libp2p
nim-libp2p copied to clipboard
vacp2p
bump version
eh 1.0 would imply api stability, don't thing this project is there yet
So we're running unstable code in prod?
On Sat, Dec 19, 2020, 02:26 Jacek Sieka [email protected] wrote:
eh 1.0 would imply api stability, don't thing this project is there yet
— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/status-im/nim-libp2p/pull/493#issuecomment-748441118, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAILFRJN4DU26AORUMINJHLSVRPUXANCNFSM4VBYZ5SQ .
regardless of the stability of the code itself, we're running on top of an unstable api / abi, meaning that when libp2p changes projects that depend on it have to change also - releasing 1.0 tends to be associated with not breaking backwards compatibility frivolously any more
That is what major versions are for. For better or worst the api/abi we have right now needs to remain stable to not break production code. This to me deserves a major version. If/when the api changes, the major version will change as well. We're definitely far from being mature and the api will change, but we're stuck with what's out there as of now and that to me is a major version.
Of course this is one of this topics that tend to be a bit controversial, so your views might differ dramatically.
On Mon, Dec 21, 2020, 09:56 Jacek Sieka [email protected] wrote:
regardless of the stability of the code itself, we're running on top of an unstable api / abi, meaning that when libp2p changes projects that depend on it have to change also - releasing 1.0 tends to be associated with not breaking backwards compatibility frivolously any more
— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/status-im/nim-libp2p/pull/493#issuecomment-749046328, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAILFRIFX5YUN3WMNJU45B3SV5V2ZANCNFSM4VBYZ5SQ .
needs to remain stable to not break production code.
or the production code users need to be aware that the abi is not stable, either is fine - version numbers are mainly a form of asynchronous communication / informal promise signalling the intent of upstream to user of the library - ie the latest gossipsub changes from the other day break abi/abi, as do the latest switch changes as will the upcoming switch changes, as did the close changes and so on - you can call it 1.0, but naming a donkey a horse doesn't make it run any faster.
you can call it 1.0, but naming a donkey a horse doesn't make it run any faster.
That's where the disconnect is. It seems like you're perception of versions implies maturity of the code/api/abi, while IMO versions were never about that, they are a promise that we will not inadvertently break client code by changing the library's shape. We're free to release as many major versions and as often as we see fit, a major version in and out of itself won't make things faster or less ugly, but it gives us a framework to consistently track and communicate this changes.
- ie the latest gossipsub changes from the other day break abi/abi, as do the latest switch changes as will the upcoming switch changes, as did
BTW, just to clarify, I don't think the api changed for any of those, so they are at best a minor version change?
Also, we don't have to overthink this, no semantic versioning or any of that stuff - KISS.
- Major version - api/abi breaking changes
- might also include big futures that doesn't affect the existing api/abi but changes enough stuff to deserve it's own version (I'm willing to be flexible here)
- Minor version, non breaking changes - should absolutely guarantee api/abi compatibility with previous
major.minorversions - Patches, small non breaking changes - bugs, small refactors and cleanups
here's a sample of breaking changes from last week:
https://github.com/status-im/nim-libp2p/pull/495 https://github.com/status-im/nim-libp2p/pull/490 https://github.com/status-im/nim-libp2p/pull/480
but sure, if you want to police a major version update for each of of these, you can - it's just a lot of administrative work - instead of simply saying that the api is unstable and keep it at <1.0 - ie the reason to not do versions is that it comes with maintenance overhead, and the project simply isn't there yet (see also the 1.0 roadmaps and the amount of deprecated code and warnings in the general)
but sure, if you want to police a major version update for each of of these, you can - it's just a lot of administrative work - instead of simply saying that the api is unstable and keep it at <1.0
Even if you stick with a <1.0 scheme, you still all the same overhead without none of the benefits of a major version, that is unless you're suggesting drop versioning at all?
no semantic versioning
a bit pointless to do versioning without meaning - semantic versioning provides a framework that nobody has bested yet
drop versioning
well, yes, until the library is in a "ready" enough state by some minimum quality standards that are outlined in the 1.0 ticket, I'd say there's no point in releasing versions - specially not when there's no working package manager to go with it.
a bit pointless to do versioning without meaning - semantic versioning provides a framework that nobody has bested yet
Well, I did provided an outline of a simple versioning scheme here https://github.com/status-im/nim-libp2p/pull/493#issuecomment-749092024. The point is to show a solution that would avoid all the complexity of a pure semantic versioning scheme while retaining most of the benefits.
until the library is in a "ready"
How do you determine when it's ready?
I appreciate you being mindful of the overhead this might bring to the team, but consider this points as well:
- Nim's package manager, albeit broken, is still used and relied upon by the community, which makes it a valuable distribution channel
- nim-libp2p, in its current form is stable enough to rely for production grade usage, which means that others can start benefiting from using it right now
- making nim-libp2p available over commonly accepted distribution channels will benefit us with greater adoption which leads to valuable user feedback
- the overhead from maintaining a simple (as outlined above) versioning scheme is minimal and at the very least should not interfere with the teams workflow
For me it's rather unexpected that libp2p is still on version 0.0.2, and has been for over a year. This communicates to me that versioning is not used at all. No versioning means that any code that uses libp2p has to pin to a certain commit hash, and there is no information about backward compatibility when updating to a later commit.
The simplest way to remedy this is to move to 1.0 and bump the major version on breaking changes. Which is also what semantic versioning suggests.
there is no information about backward compatibility when updating to a later commit.
there is information: every commit can be expected to break it, as is practically the case in past commits and in the nearest future given that several breaking changes are planned in the coming days, weeks and months. Compare the stability guarantee in https://tokio.rs/blog/2020-12-tokio-1-0.
The discussion seems to revolve around two questions, perhaps it's wise make them explicit:
A. Should libp2p have a version < 1.0.0 or >= 1.0.0? B. Should libp2p have version numbers at all?
Regarding question A: I tend to lean towards >= 1.0.0 because libp2p is in production, but I can live with < 1.0.0 because the API is not yet stable.
Regarding question B: Not having versions for a library violates the principle of least surprise. It's an oddity that causes confusion and friction. I really think that libp2p should have versions.
well, it is in the nature of things that they get used in "production" before becoming stable by pioneering projects - in terms of managing expectations though, 1.0 usually implies some sort of thinking around stability, such that others can rely on it in their project without worrying about the mat being pulled from under their feet - for example, one could expect this to be the point where one starts a bugfix-only branch etc - it speaks for the quality of the project when this process is deliberate.
