Please don't inaccurately call 1.0 a "stable release"

[wbt]

---

Issue

As noted here:

Even the decision to just say "we're going to call beta37 the 1.0 stable release, despite all the good reasons why we've not considered it a stable release and despite all the important issues in it we've been finding and fixing over more than the past half year" seems like a somewhat arbitrary marketing-driven versioning decision and probably a bit of a lie on the "stable release" language which seems more likely meant to satisfy some VC or manager or PR purpose than to necessarily have the appropriate technical backing. (To me, changing to 1.0.0 could just be used to signify a breaking change; it doesn't have to be conflated with completion of a major milestone or even stability in the release, as seems to be conflated in Web3. Hyperledger Fabric put their first LTS release at whatever version number they were at when they thought they were ready, specifically 1.4).

And here:

(@wbt wrote:) I'm not convinced this project is ready for a "stable release" label/claim. I am in favor of steps back toward semantic versioning and having some base version that can be patched/modified to resolve outstanding issues alongside appropriate bumps in the semver number depending on what gets changed, as things get changed, without burying @nivida or anybody else under a mountain of outstanding action items that all have to get changed at once before any new useful developments can be released.

(@nivida replied): The missing announcement will explain this closer and any further or required questions can be asked in the publicly accessible EJC discord or with an issue here on GitHub.

This is that issue on GitHub, for focused discussion.

Calling the pending release 1.x seems appropriate based on there being major breaking changes from any 0.x version. Calling it stable just does not seem appropriate, seeing how unstable that code has been.

Why must "stable release" coincide with the breaking-changes version bump to 1.x? There does not appear to be any good technical reason for it, though there may be hidden other reasons that @nivida has so far consistently refused to elaborate on.

This issue proposes NOT calling the outcome of this PR a "stable" release. It's not really stable and there are good reasons why it was not put out as a stable release several months ago. Just call it the version number it's at (1.0 or 1.2 seeming most likely candidates) and continue patching/modifying that version with appropriate bumps in semver depending on what actually is changing. If/when the software reaches stability, have a discussion and make an announcement then.

The publicly available evidence is that the current version is not "stable" and by simply waiting for "the missing announcement" it'll be too late and damage will have been done by then. If there are good reasons to call it "stable," let's have that discussion here, before just putting it out there as an assertion of fact reached by one person's opinion or a small group's closed-door discussion.

[adrianmcli]

I think this is an issue of semantics and I am inclined to agree with your sentiment. This is only stable in the sense that it is relatively more stable than the breaking changes introduced in beta38-onwards. It's obviously not perfect and as you said, there are issues fixed in the past half year that would indicate this not being stable. However, the API is arguably a lot "more stable" than the twists and turns that was introduced in beta38-onwards.

Disclaimer: I had no hand in crafting the language of the 1.0 release, I am just happy that we are abandoning calling everything a betaX while making drastic API changes. Just offering my two-cents as a bystander.

[wbt]

I think this is an issue of semantics and I am inclined to agree with your sentiment. ...I am just happy that we are abandoning calling everything a betaX while making drastic API changes.

@adrianmcli Thanks for chipping in. However, web3 does not appear to be abandoning that practice. Starting with the release of 2.0.0-alpha, I'm anticipating a 2.0.0-alpha2, 2.0.0-alpha3, etc. with breaking changes likely between (for example) 2.0.0-alpha21 and 2.0.0-alpha22. It is an issue of semantics, specifically semantic versioning.

In semantic versioning, a major version number increase does not need to mean stability. It only signifies that there are breaking changes from the prior version. Web3's insistence on conflating the two so strongly, when stability and major version number ought to be independent of each other, is causing the kinds of frustration that we saw with all the breaking changes in the 1.0.0-betaX series, and seriously harming the project.

We still do not know why there is such a strong insistence on putting something out as a "1.0.0 stable release," though the insistence is strong enough to have thrown out semver in the first place and now holds up this PR, among other impacts.

The insistence seems so strong that there might be a contract somewhere saying "@nivida gets €xxxxx (or a job retention/promotion or other result of value) if and only if a 'v1.0.0 stable release' of web3.js is published by date Y; this contract shall be strictly interpreted according to its text." It wouldn't be that unusual for a poorly worded funder milestone. Maybe there's some PR or marketing angle; maybe we'll never find out. If there's a good technical reason for calling this release "stable," it should be noted here in this discussion.

It has breaking changes from 0.x, which is sufficient technical reason to call it 1.x, so that part isn't in question here.

I think the decision of when to call a release stable should be a community decision based on technical merit, not an arbitrary decision contrary to available evidence imposed by someone who seems so strongly motivated by undisclosed factors that the project suffers from resulting decisions.

[OFRBG]

From the semver standard and as this user echoes here: semver/semver#363 (comment), 1.0.0 does carry some special meaning. Before 1.0.0 you're still signaling that the product isn't there yet. Once you get to 1.0.0 you are stating that it is ready for anyone to come and use the release.

As for the standard, 1.0.0-x < 1.0.0, so bumping from beta to 1.0.0 adheres to semver and calling it public stable release, passing QA and community requests, matches the general notion of 1.0 signaling some sort of production-ready completion.

[wbt]

If this project were really following semver as outlined there so far, it wouldn't have gone through the 1.0.0-betaX series with all those breaking changes as it did. It might have gone with 0.21.0, 0.21.1, 0.22.0, etc. instead. Jumping directly to "well, we think we're in striking distance of 1.0, so we're going to abandon semver and just power through this beta series" was a mistake (driven by who knows what factors) that has had serious negative consequences for the project and its users.

Now, a year later, how do we clean up from that mistake and move forward? We probably can't go from 1.0.0-betaX to 0.21.x because the inequality is in the wrong direction. By jumping ahead so prematurely, the only place to go from here numerically is 1.0.0. Our hands now are somewhat tied by an earlier erroneous choice.

Doing a 1.x release could be a very helpful step back toward semver. While not necessarily 100% there, it's motion in the right direction. It would also be a lot better than just continuing on through the beta series, mixing major breaking changes in with minor backward-compatible patches.

The text accompanying the release (e.g. "stable version") sends a much stronger signal than a number about whether or not the software should be considered stable. If it's not stable, as evidence indicates, it shouldn't be declared as such in the accompanying text. Because the semver number does carry that meaning for some people, the text should probably state very explicitly that it should not be considered the stable first release, "please stay tuned for that."

[wbt]

Responding to @nivida's comment here (a more appropriate channel for this specific discussion point, and one where I am not locked out):

@wbt Truffle and OpenZeppelin was the main actor to release beta.37 as 1.0 stable version of web3.js because it's used widely over the community. We were discussing this for a long time and I was first against this decision and would have liked to follow the path with the new architecture I've written since I've started here but this isn't possible because some projects were relying on the internal API and architecture of web3.js. Splitting this up between a 1.0 and 2.0 version of web3.js will give us the possibility to not break already existing DApp's. The new architecture in 2.0 does provide the same public API as we had before just with new core modules and some additional features but the real benefit of 2.0 is that we are able to use the latest features of JavaScript. Version 1.0 and also 2.0 will be maintained and improved by me and the community which wants to be involved.

Splitting functionality between 1.0 and 2.0 version is fine, and not breaking existing DApps is a valuable goal. Doing this is absolutely still compatible with not inaccurately labeling a release as "stable." Please go ahead and call it 1.0.0 (or 1.2.0) and 2.0.0, and use semver from there, but just don't say "stable" in the release announcement when that is inaccurate. That's all this Issue is about.

[michaelsbradleyjr]

If this project were really following semver as outlined there so far, it wouldn't have gone through the 1.0.0-betaX series with all those breaking changes as it did. It might have gone with 0.21.0, 0.21.1, 0.22.0, etc. instead.

The rapid succession of betas that diverged more and more from the codebase <=1.0.0-beta.37 was clearly problematic — lots of teams and individual developers felt frustrated and concerned, including the team I'm part of. In hindsight, the heavy-duty refactoring and breaking changes >=1.0.0-beta.38 should have been part of a 2.x series to begin with.

As for the de/merits of a -pre.N series of releases containing breaking changes across N+1... well, when done on a major semver bump (e.g. X.Y.Z to (X+1).0.0), I don't see how that's generally objectionable. Common wisdom and common sense suggest that development ought not proceed in a wild fashion, and even major releases ought to maintain some continuity (project work should be well scoped), but if a major refactor is needed to pave the way forward, then bring on the breaking changes. A series of alpha releases can help lay bare what's going to have to break — it's not always clear on -alpha.0. And providing those releases via the registry can make the in-progress work more accessible compared to users having to clone the repo and build it themselves (adventurous users/devs can be a great help in finding bugs and breakage).

When shifting from alpha to beta, and definitely once deep in a beta cycle (and this is by common convention/sense more than anything else), ramping up the pace of breaking changes is a recipe for user confusion and project misdirection. If that's actually necessary, then brakes need to be applied and the trajectory recalculated. I think that's what happened in this case, though perhaps not quickly enough.

michaelsbradleyjr/web3.js@comparing-v0.20.6...michaelsbradleyjr:comparing-v1.0.0-beta.37

That's a pretty massive set of changes spanning a long time. I didn't get started with web3 until July 2018, so I can't offer too informed an opinion on whether that change set represents a good candidate for a more thought out series of 0.X releases... but probably, sure. It can't be undone now, though.

On the other hand, the team I'm part of has been heavily using beta.37 since it was released in Dec 2018. While not perfect by any means, it's been... well, pretty stable. The official docs website is a bit out-of-date w.r.t. beta.37 and that's caused us some confusion, but on the whole it works reliably.

The change set for the 1.0.0 release (or 1.2.0, whatever) is fairly modest: v1.0.0-beta.37...release/1.0.

Assuming that 1.x going forward will have no more breaking changes (semver!!) — only bugfixes and maybe some features here and there — I don't get why it's a big deal to label it as a stable release, i.e. as if that's horribly inaccurate.

[nivida]

@wbt I was the same meaning as you that beta.37 isn't stable. This was the topic of our discussions with the involved projects and active contributors for the last 3-4 months. I've removed the word stable from the coming release announcement and will call it v1.0.

2.0 got released as 2.0.0-alpha and will get patches in the next months until I've written down the spec for it and until we have jointly defined how the future API and architecture will be.

[wbt]

I've removed the word stable from the coming release announcement and will call it v1.0.

@nivida Thanks much!

I've responded to the rest over here, where it's more specifically on topic.