I want to know the exact difference between the semver notations in package.json. Can someone explain me.
I think the npm documentation explains it well: https://docs.npmjs.com/cli/v6/using-npm/semver#advanced-range-syntax
Since there is a lot going on, perhaps a brief explanation of the two most common:
The caret modifier (^) will automatically go the highest minor and patch version, unless the major version is 0. In this case, will only update the patch version.
The tilde modifier (~) will only go to the highest patch version. So ~ and ^ are equal when the major version is 0.
Semver notation isn't specifically used in package.json.
If it's followed (*1), it helps developers to understand what to expect from any particular update. Imagine you want to bump the version of a library, and you see that the difference is in the major part of the version (n in n.*.*). This can point out to potential repercussions of upgrading the package - according to SEMVER MAJOR version when you make incompatible API changes,.
*1 It's not always followed by developers. One prominent example is React Native. The developers have never released a Major version, and treat MINOR as MAJOR
I got this from node js documentation. There is a pretty well explanation for question.
https://nodejs.dev/learn/the-package-lock-json-file
In package.json you can set which versions you want to upgrade to (patch or minor), using the semver notation, for example:
if you write ~0.13.0, you want to only update patch releases: 0.13.1
is ok, but 0.14.0 is not.
if you write ^0.13.0, you want to get
updates that do not change the leftmost non-zero number: 0.13.1,
0.13.2 and so on.
If you write ^1.13.0, you will get patch and minor releases: 1.13.1, 1.14.0 and so on up to 2.0.0 but not 2.0.0.
if you
write 0.13.0, that is the exact version that will be used, always
Related
The semantic versioning system states that a backwards compatible bugfix means that you increment the patch version number (z in x.y.z). It also states that a backwards compatible feature addition should be introduced by incrementing the minor version number (y in x.y.z).
What if both of these things have been added a new release is due? Does one only increment the minor version number?
Semver is a great framework when each addition gets its own release. In this case, you would have ideally released the patch version updates for each bug fix, and then the minor version. However, having collated all those things together, your intuition is right. You can simply bypass the patch versions and bump the minor version. Just make sure to mention the bug fixes in the changelog to help your users know what has happened.
And remember, frameworks are meant to enable you to do things quickly, rather than be strict guidelines. So, nothing out there says that what you're doing goes against semver, it's just adapted to your way of working.
I'm reading the Rust book. Specifically this section about Semantic Versioning used by Cargo.
What doesn't really make sense is this:
The number 0.8.3 is actually shorthand for ^0.8.3, which means any
version that is at least 0.8.3 but below 0.9.0. Cargo considers these
versions to have public APIs compatible with version 0.8.3, and this
specification ensures you'll get the latest patch release that will
still compile with the code in this chapter. Any version 0.9.0 or
greater is not guaranteed to have the same API as what the following
examples use.
According to the rules for semantic versioning, a change of the minor version (from 0.8.3 to 0.9.0) can NOT contain changes that break the public API. Why does Cargo think that the public API for these 2 versions may not be compatible? Is it because the major version happens to be 0? If we were dealing with a case where the major version was > 0 (Ex. 1.8.3), would specifying 1.8.3 in Cargo.toml allow Cargo to install version 1.9.0 then?
As documented in the Specifying Dependencies chapter of The Cargo Book (emphasis added):
The string "0.1.12" is a semver version requirement. Since this string does not have any operators in it, it is interpreted the same way as if we had specified "^0.1.12", which is called a caret requirement.
Caret requirements
Caret requirements allow SemVer compatible updates to a specified version. An update is allowed if the new version number does not modify the left-most non-zero digit in the major, minor, patch grouping.
[...]
This compatibility convention is different from SemVer in the way it treats versions before 1.0.0. While SemVer says there is no compatibility before 1.0.0, Cargo considers 0.x.y to be compatible with 0.x.z, where y ≥ z and x > 0.
The Semantic Versioning Specification (SemVer) defines:
Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.
So starting with 1.0.0 is considered stable.
When starting a project normally version 0.1.0 is used and gradually increased, there is a point where the project can have something like 0.20.3 for months/years and it is "stable".
Therefore would like to know what could be considered good practices to follow besides the criteria, arguments before bumping a project to server 1.0.0.
How you are dealing with this?
If there are not issues/code activity in 3 months the version is dumped?
The development team decides when they have version 1.0.0. It is possible for a project to remain in experimental/prototype mode for very long periods of time. The only thing that matters here is whether the interface and implementation can be considered complete or not. What are your goals? Do you have all the planned v1 features in place? Do you have doubts w.r.t. implementation conformance to the documented interface?
Some teams don't have workflows that map onto the full semver spec, but they use packaging/release tooling that requires a semver version string. In order to be legal, they never release version 1.0.0, so any version bumps literally don't have full SemVer semantics. See #4 in the spec.
When I see SomeLib.0.20.3.pkg I assume it is not stable. A breaking change can occur on the very next minor field bump, whether or not there have ever been any such changes in the past. SemVer is a contract that allows the SomeLib developers to break things without notice in this particular case.
There is nothing in the spec that precludes a team from issuing a 1.0.0 and then returning to a long sequence of 0.x.x releases if they so desire to operate that way. This is similar to, but not exactly the same as using prerelease tags. When you issue 1.0.1-prerelease you are at least implying intent to release a work derived from 1.0.0 that is a bug-fix, but the prerelease tag is warning label that you are not yet certain of the safety of the changes you made. Following on from 1.0.0 to a sequence of 0.x.x releases says you might not even be deriving from 1.0.0 anymore. Basically, all bets are off again.
If you require any further elucidation on this matter, please ask, I am happy to try to answer any questions regarding SemVer.
Let's say my npm package of 1.0.0 publicly exposes a function called foo for users to use among many other functions and features.
I then remove the foo function which will break for all the users who are using this function.
NPM says:
Changes which break backwards compatibility: Major release, increment the first number, e.g. 2.0.0
I'm quite confused exactly what this means.
Should the major number be updated always if we break a change for users even if it's just a small change such as removing a function?
At the moment I update the major number whenever I possibly break a publicly exposed feature. I see npm packages with small major versions and thinking that I am incorrect in doing this as I am updating my own packages major number very fast.
Each API change (e.g. removing endpoint, function from lib, or changing behavior of endpoint/function) which may impact clients should update MAJOR number. MINOR and PATCH tells client that library/API is stable for one MAJOR version.
Given a version number MAJOR.MINOR.PATCH, increment the:
MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.
You can read more at http://semver.org/
A colleague got into a casual argument about the first version of a module. We're wondering if 0.0.1 should be the initial release. I think 0.1.0 is the proper first version, as 0.0.1 implies an increment of a patch, and a patch implies a prior release. So from my understanding, there would have to be a 0.0.0.
I skimmed http://semver.org docs, which do say that 0.1.0 is usually the initial release, but I didn't see any rule against having a minor number set to 0 when the major version is also 0.
Does anyone know if 0.1.0 being the lowest possible version is a formal rule, or just a convention?
The semver 2.0.0 specification doesn't preclude it. The FAQ does recommend starting at 0.1.0 though.
How should I deal with revisions in the 0.y.z initial development phase?
The simplest thing to do is start your initial development release at 0.1.0 and then increment the minor version for each subsequent release.
There are no rules here and conventions are loose.
When the initial major number is zero, all that is guaranteed is that higher numbers come after lower ones. All the semantic versioning guarantees about "this is a bug fix" or "old functionality still works" only apply to version one or later.
While there is a loose convention of 0.1.0 being the lowest version number, there are those that would argue it the first version one shares with others. The specification of semantic versioning simply sees the leading zero and washes its hands.
As per the semver calculator (https://semver.npmjs.com/), it is not recognizing the versions which start with 0.0.x.Semver Calculator Screenshot
Semantic versoning (semver) is about 'safely moving your project forward.' — from the last line of the second para of the docs Introduction.
By this definition and purpose we SHOULD bump our version number for each release (bump version then commit).
From docs (Rule #2): The version numbers (MAJOR, MINOR, and PATCH are non-negative integers).
If you started at 0.0.0 you must bump to something likely 0.0.1 or 0.1.0 where the MAJOR '0' indicates you are still in development.You could very well bump straight to 1.0.0 where the MAJOR '1' indiciates an initial public release.
Remember the rules, if you bump MAJOR you must reset MINOR & PATCH to '0' ... If you bump MINOR, you must reset PATCH to '0'. This prevents you from bumping all three simoustaneously.
In order to release 0.0.0 you must start at 0.-1.-1 or 0.0.-1 in your package.json (YOU CANNOT BY RULE #2) such that when you release (bump version then commit) you have a release with semver number 0.-1.0 (YOU CANNOT BY RULE #2) or 0.0.0;
The FAQ for semver says "The simplest thing to do is start your initial development release at 0.1.0 and then increment the minor version for each subsequent release." They are speaking about the actual release; after you have done the (bump version then commit). This is mentioned because you could have a release numbered 0.0.1 which indicates you FIXED SOME BUGS.
0.0.0 = Initial Development Release (Does Not Exist)
0.0.1 = Bugs Fixed Since (0.0.0 | Where You Began)
0.1.0 = Features Added Since (0.0.0 | Where You Began)