I am working on a SaaS application with node.js using npm for managing dependencies. I am trying to decide what to do about the version number. Our release model will be to market features and release when ready, rather than marketing versions.
I am looking for advice on the version field for package.json. Since we won't be publishing the app to the npm registry, I can really use whatever version number I want. I really don't want to maintain a typical version number like 1.0, 1.2, 2.0, etc. Since a release is simply a project that ships when ready, dates make better versions for me, like "RELEASE_20130104", but npm requires that the version field in package.json be parseable by semver rules.
I am interested in hearing what the rest of the community has done for SaaS npm-based apps.
Requirements:
Effortless - I don't want to waste time debating between 1.2.0 or 2.0. It's just the next release.
Must satisfy the npm version syntax rules.
Nice-to-haves:
Scriptable through a build process, like extracting SVN branch and
revision number.
Version means something, like the release date.
Solutions I have come up with:
Strictly follow semver major.minor.patch pattern. This will require separate scripts for different release types and will be a nightmare for pre-release builds.
Express the release date in semver format like "2013.01.04"
SVN revision number + branch or tag name like "21484-BugFix21". Downside there is that non-release builds' versions don't tell you what release version they are branched from.
Pick a dummy version and never change it like "1.0.0". Track the version in the format I want in a separate field, like "appRelease": "2013.01.04".
I don't expect right or wrong answers. There are a ton of solutions. I am looking to see what approaches others have taken in the past.
Related
What is the policy when one enforces a newer (Node.js) engine version?
Is it semver MAJOR or semver MINOR?
Context: I'm the author of a package with 2k stars on github (30k downloads per week) and I recently enforced Node.js v14 (because I'm starting to use optional chaining and null coalescing everywhere), and made it a new MINOR version.
But some of my users are complaining and asking me to make that change a new MAJOR version.
Also previously, nobody complained when I enforced Node.js v10 on a MINOR version.
I can't find any resource about that matter, even the semver spec does not specify this (not even in the FAQ section). The spec only talks about the API.
I want to keep my project in line with the correct policy.
Quoting Isaacs from Twitter (#izs), author of the semver npm package (and by the way founder of npm):
I've always considered SemVer Major to mean "you will have to change something on your end to start using this update".
If the previous version worked on platform version X, and the new version requires platform version X+n, then that qualifies, yes.
This has been discussed here in many threads as well SemVer discusions. Some claim it is subjective, but I think if you were to replace the opinionated terms (API, Package, Product) with something like OBV (Object Being Versioned), you will see that spec and most of the knowledgeable participants agree with each other.
If your customer's build environment is broken because you issued a minor or patch release, they have every right to complain. The SemVer spec really focuses more on API versioning, than packages, though it does mention the later in a few places. So the key here is, most of us never actually version just an API, we version packages and the manifests within them, which also implicitly/explicitly include transitive dependencies.
The whole point of SemVer is to communicate risks to consumers of those OBV's. As a publisher, you are responsible for the entire dependency tree that you include in your OBV's. You can chose whether to implicitly or explicitly introduce a breaking transitive dependency into your OBV, therefore it is your responsibility to inform your customers of the risk by bumping the major version.
We are building a Node.js app. As we are practicing Continuous Delivery with Trunk Based Development we would only have one branch and one build to work with.
For several reasons including legal requirements we are expected to deliver a patch version for the currently released version any time we are developing a next feature release. What's more: There are features and/or activities that would not make it to the next feature version.
Obviously any new features have to be excluded from the patch release, any we-will-not-make-the-next-feature-release stuff has to be excluded from the next release.
In order to test (and ship betas) we are building and testing three versions of the product, say 1.0, 1.1 and 1.2.
Exclusion of features is done using feature toggles.
Question: How could I exclude dependencies only valid for next feature release or even later from being put into the node_modules during build?
If it were for two lines I would try something using the optional dependencies of package.json.
Is there any other way to make sure:
dependencies for 1.1 and after are not making it into 1.0
dependencies for 1.2 and after are not making it into 1.0 and 1.1
require(...) does not fail for not existing dependencies (wrapping with feature toggle???)
Is there a way to avoid keeping three package.json's and pick the "just right" one during build of each version?
Here's my project development process:
feature/feature1
feature/feature2
feature/etc..
master
production
I develop my features on the features branches, when I have finished with a branch, I merge it on master and delete it via github ui. CircleCI detect the merge and deploy the master on a staging server.
Later I merge manually the master branch onto the production one, and CircleCI deploy to my productions server.
I would like my package.json version to bump each time I merge a feature branch to the master branch (via github UI). But I have no idea if
Github allow to do so (if yes please can you explain to me?)
It's a good process
I'm aware I could do it via npm version command when I merge master onto production, but I do need the version to be updated on the master automatically when I merge a branch into it.
Don't hesitate to criticize my way to proceed and tell me yours. :)
Thank you
I don't think Github offers any such feature. But there are some grunt modules that do this during build time. You could probably script this or have a make file that does this for you as well.
I don't think this is good way of versioning. After you are done with a feature, you have to decide if the changes you have made are minor or major. Some times you might commit breaking changes. Just incrementing the version number form 1.0.1 to 1.0.2 or say 1.1.0 to 1.1.1 (every time) will not convey the magnitude of these changes. Best Practice: Software Versioning
The best practices for versioning are already covered here.
We manage versioning manually where I work. Before each release we create a tag (v1.0.3, v1.1.4..etc) and then create a release on Github. In the description of the release we put all new commits. Going through the commit message gives us a good idea of the changes that were made. If the changes only involve bug fixes and minor feature additions we will increment the minor number ie. 1.2.1 to 1.2.2.
If a major new feature is added, we increment the major version number ie. 1.2.2 to 1.3.0. When we add many breaking changes we go from 1.3.0 to 2.0.0.
Sometimes we are loose with versioning. Our API is not public and the only reason we use versioning is for deploying and for rolling back. If you are expecting to make you work open source and or expecting to make your work available through some kind of package manager, like say npm, you should follow semver versioning strictly.
Does the npm registry expose release notes in a standardized way? I've seen release notes in:
The README.md
On GitHub as a tagged release with no description
On GitHub as a tagged release with a description
While SemVer at least lets me know if there's a breaking change, it would be really nice to review what features or bug fixes a package author may have added.
There is no such standardization as it's completely up to the project developer(s) to define how such information is conveyed. Some might have a NEWS file, others might have a Changelog.md, or yet others may have it in the places that you mentioned. The locations and file formats can vary widely.
It is possible that npm could adopt some optional thing that can automatically display some plaintext file using some kind of fixed naming scheme (and possibly falling back to a git diff if a git repo is defined in package.json), but as of this writing there is no such feature.
When browsing the packagist.org repositories you see packages with these version numbers e.g. If you look at the Phpunit repo
There are a few instances
4.5.x-dev
4.3.x-dev
4.2.x-dev
Do these packages contain the current work the developers are performing towards basic updates, security and bugfixes etc on an otherwise basically stable package?
These are the dev branches. These are unstable and contain bug fixes, etc. This will eventually be released as 4.5.8 for instance (if the library is still supported).
You can get it by using 4.5.x-dev or 4.5.*#dev as version constraint.