[baseline practices] Versioning about package-maintenance

[mhdawson]

I think there might be 2 different things being covered in this discussion so far:

• Advice we'd have for module owners with respect to Versioning that might make their life easier. (In the spirit of "if I can just read and adopt best practice it's easier than figuring it out on my own"

• What might make it easier for package-maintenance team members to help out with a package.

I think both are good but we should probably treat these as 2 different concerns until they are fleshed out enough to see where they overlap.

The first I think should be easier to define. The second I think we can come up with some ideas but I think the second we need to have some of the pilot modules on-board/engaged to makes sure what is discussed makes sense to maintainers.

[mcollina]

Can we add a note that increasing the minimum version of node required is a breaking change?

[ghinks]

Semantic Versioning Best Practices

Using Semantic Versions <1

Much like @mcollina I have been known to do a release or twenty before getting to version 1.0.0. But I been living behind the firewall for a long time.

Versions with numbers major numbers x.0.0 do kind of psychologically mean more than numbers with only minor or patchches 0.x.x.

The public eco system is littered with packages that do already start <1. This against the best practices about semantic versioning from npm.

What @rxmarbles is asking is for baseline best practices for package maintainers.

As package maintainers it is highly unlikely that we would be adopting or offering help to a package that were not already popular. Popular packages tend to be on major semver version numbers already.

So I think it is very unlikely that we get the option to carry on using 0.x.x version numbers. If we can accept this as the most highly likely scenario then we can set this aside the <1 as not likely to be an issue and accept the best practices from NPM and continue with the major naming convention that will in all likelihood be in place.

So I think the best practice is to follow the NPM convention. This is least and most easily addressed issues raised by @rxmarbles.

If a package were to be maintained and it were not on a major release then the first fix should be to put it on one.

[dominykas]

0.x.y is undefined by semver

It is defined, and it is a valid use case, from https://semver.org/:

Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

---

I don't think this group should define 1.x as a recommendation simply because there's clearly people who don't agree with that. Yes, npm (et al) have a different opinion. That's fine. At the same time, there is a crowd of users who are screaming "why are you bumping all these majors!" at you, as a maintainer, and that creates undue stress, and 0.x is a good way to avoid that stress during initial development.

I think that there's several points in this discussion that can help us solve it, without perpetuating the circular arguments:

1. There are different opinions - we agreed that it's safe to include them in various docs as such - opinions (with pros and cons). Saying something along the lines of "npm will initialize the packages at 1.0.0, because xyz reasons. semantic-release will automatically bump 1.x on first release too. Semver allows 0.x.y for initial development because abc. There is no strict consensus on which should be your starting point." is enough?
2. As @ghinks mentioned, from the perspective of this group stepping in to help a maintainer, we're pretty much never going to have to deal with a 0.x, but even if we do - for a long lived package, which might have become unmaintained over time, the API is by definition stable (there were no changes), therefore a 1.x bump, as a first step, is fair game, even if in some cases security releases under 0.x may still be required.

---

Would we want to make a recommendation, that ideally maintainers should avoid breaking changes, if at all possible? Is that a best practice?

[sam-github]

I thought this debate was settled years ago, when npm went to 1.x as default.

I absolutely understand that 0.x was node package practice for "its not stable yet", and it was common on npm, and node.js itself did this until io.js forked and went to 1.x (because ... "semver"). Not everyone agreed, and of course it didn't mean that every existing working package suddenly decided to republish a 1.x, or every developer decided to abandon the old way.

Personally, I support the first published package being 1.x (or more specifically, having a semver defined meaning, a major that is >= 0).

I guess its possible to publish a package you don't expect people to use, but should the package guidelines address that use-case?

If you do expect people to use it, or even 1 person, they deserve to get semver, so they can use it in their package dep-spec, and know what the package version numbers mean.

If every version of the package has different major, that's ok. numbers are cheap, and the meaning is absolutely clear. It means the API isn't stable, but it doesn't mean that any more than if every version has a different minor.... or wait, actually, if every minor is different there is no way to know if the API
is stable or if the author is using the "minor in x" non-semver definition...

0.x.y is undefined by semver, so people made up two incompatible practices, trying to fit major/minor/bug into only two numbers, x and y, leading to a debate over whether x or y is incremented for minors.

Why even get involved in this when we have semver, with 3 numbers?

The package guidelines aren't going to be enforced (well, npm install does semver...), and disagreeing with the guidelines won't (I hope!) lead to ejection from npm or social awkwardness, but if we don't at least recommend that published packages use semver and start with a non-zero major, I think we're wandering back into the weeds, weeds we'd been slowly getting out of.

[vweevers]

Would we want to make a recommendation, that ideally maintainers should avoid breaking changes, if at all possible? Is that a best practice?

I'm leaning towards no. I've only encountered a handful of cases where breaking changes were not fully justified. For example, a while back there was a wave of packages switching from callbacks to promises. That's a kind of breaking change that requires refactoring on the consuming side, not to mention there's a crowd that still prefers callbacks. On the one hand, if the packages were forked instead then consumers would have a choice. On the other hand, that'd mean the maintainer now has two packages to maintain. 🤷‍♀️

[mcollina]

I strongly disagree with npm advice to start at 1. Mainly because I typically change my mind 10 times (or more) before stabilizing my API, so I take full advantage of the 0.x series.

What is really missing is a tool that helps backporting changes to previous major lines.

[dominykas]

What is really missing is a tool that helps backporting changes to previous major lines.

semantic-release has a beta feature to make that a lot simpler. Not sure when that's going stable, though...

There's also https://github.com/sindresorhus/np and similar tools, which can be recommended (I haven't used this particular one, but I've been looking into this are lately).

[ljharb]

@mcollina we’ve got plenty of numbers; starting at 1 just means you might end up at v15, and that’s ok.

[mcollina]

From semver:

Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

Then I upgrade to 1.x.y once the API is stable enough.

[ljharb]

I personally subscribe to an older edition of the spec where in 0.0.x and 0.x.y and x.y.z, x is always the major, y always the minor, and z` patch - but either way, "anything may change at any time" is true of every single possible version number - it's just that breakage would require incrementing the major.

[ghinks]

Glad to lend a hand here, I am quite happy to make a draft even if it is just to be shot down and replaced. :)

[mcollina]

I concur @ghinks!

[ghinks]

consensus

As part of the original discussion here we were hoping to reach a consensus. I was hoping to reach consensus quickly on the 1.x issue and move onto more of @rxmarbles items on this topic.

But as @vweewers, @dominykas and @sam-github have pointed out there is a wide view of opinions and that as many packages do not conform to the best practices we will have to take a very practicle approach.

How about this.

I'm going to refer to the package maintainers group as the group.

If the group adopt a package and that package is already following the semver NPM best practices then continue to do so. If however a widely used package were not on a major number then we should continue to follow the currently implemented versioning strategy that the package has been using.

We do need to reach consensus on this item and although contentious it does seem to be a bit of an edge case.

So please let me know if you have a alternative strategy that would reach may reach a consensus. But I think that alternatives that may reach consenus must be part of any further semver 1.x conversation. I only ask this so that I can move onto some of the other items that @rxmarbles has pointed out and we can move forwards. In reality this may well be an non issue for several years, depending on the packages that are to be adopted/assisted by the group.

[mcollina]

I agree.

However if there is a wildely used package I would argue that we should campaign for moving it to 1.x if they are not. Widely used means that they are definitely already past:

Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

[ljharb]

What group of users is complaining about too many major bumps? I’ve never once heard that complaint.

[sam-github]

Anything may change at any time.

Saying 0.x is defined by semver when 0.x is "defined" to have no semantic meaning is a stretch, IMO. I struggle to find a better word than "undefined". Maybe "semanticaly meaningless"?

I agree with @ghinks's "CONSENSUS" post.

Also, I might have misunderstood something about what we are talking about recommending.

I would recommend that packages start publishing to npmjs with 1.x, and that if they are already published into npmjs with a 0.x version, that their next API breaking change be 1.x.

I would not recommend that someone publish the next non-breaking change to their current 0.x API as 1.x, forcing all their existing users to up their dep specs (if they want to keep getting bug fixes) even though the API hasn't been changed incompatibly. That seems unhelpful. If its currently using old-skool versioning, I'd leave it well enough alone until the next breaking change.

[ghinks]

ok, I think we have may move on to the other issues initially raised.

[ghinks]

Enforcement through process

The next question that shall be addressed is versioning enforcement through process. Firstly
what does via process mean. It means that we can enforce some sort automated version changes when we adopt or assist with a package.

Any automated package versioning will by its nature have to do one of two things.

• work out if this is a major, minor or patch (oh, yeah like we going to trust that)
• get hints through the commit process for major, minor or patch

So let me take a giant leap of faith and assume that we will have to put comments into the commit in order for the process to work out what versioning should be applied.

If we agree on that we can then look at modules already available that enforce this strategy.

This will more than likely be a change to package that the owner will have to accept as part of our on-boarding process.

So that is the question is it ok with us to say if you want the package mainter group's assistance you have to sign up for our process that will require commit comments that enable the automated versioning to take place.

[ljharb]

Rather than only easily bypassed commit conventions, I’d rather look into tooling that analyzes entry points and API signatures and attempts to determine clear major or minor eligibility.

[ghinks]

Ok, folks, so we have a taker on the analysis by software approach. I'm all for this if it is possible. But the question of how is the important one. Let us examine some of the possible scenarios.

1. API change that can be detected as it is exposed that it would cause a breaking change and thus a major number change.
2. An internal change that does not impact an API but changes the response data, and thus is a major breaking change.
3. A feature change that is not exposed externally but maybe result in some new capabilities that may not manifest in a response, such as logging or performance improvements, resulting in minor number change
4. A simple bug fix that results a patch number change.

From the four examples above, I think only one could be detected easily and a decision made about which type of version change should be applied.

I am open to a suggestion that would make these types of changes deterministic. These are valuable discussions and we need to thrash out the possible approaches but we need to temper our wishes by what is available.

[ghinks]

Ok, for the versioning text itself , apart from what may make life easier for maintainers, how about...

Versioning

The package maintenance group recommends that supported packages follow the issued NPM best practices. Most packages that receive help are expected to already be following this guidance. However if a package is not already on a major semver release number we suggest that bumping up to version 1.0.0 on the next release.

[sam-github]

Suggest one change:

we suggest that bumping up to version 1.0.0 on the next semver major (API breaking) release.

[sam-github]

^--- I've had a number of problems with sub-sub-sub deps that upped their minimum required node.js version in semver-minor or patch releases. Its hard to work around at the top.

[ghinks]

new text for versioning

Versioning

The package maintenance group recommends that supported packages follow the issued NPM best practices. Most packages that receive help are expected to already be following this guidance. However if a package is not already on a major semver release number we suggest that bumping up to version 1.0.0 on the next semver major release.

It is also recommended that increasing the minimum required version of node is a breaking change and should be accompanied by major semver change.

[rxmarbles]

@ghinks it kinda looks like you've been doing a rough draft in the comments here want to take a swing at creating a draft and opening a PR for review?

[mhdawson]

+1 on opening a PR.

[rxmarbles]

closing as #171 has been merged