Semantic Versioning and Node-RED

[drmibell]

Not strictly a Node-RED question, but I would be curious to hear opinions on how semver is or should be used in the NR environment. While revising nodes that I contributed a few years ago, I started thinking about some specific issues, so with apologies to any "old hands" who find them trivial, these are my first thoughts.

When should I release version 1.0.0?
The classic semver question, but I noticed that about 2/3 of the contributed nodes in my pallet are at major version zero (0.y.z). Do the authors really mean that these nodes are still under (rapid?) development and may change, even in breaking ways, without warning? (I tend to doubt that.) Some of these nodes may actually have been abandoned at version zero, but I hesitate to think of 0.x.y as a red flag telling me to avoid using a node until it is stable. On the other hand, do NR users expect a certain level of support (bug fixes, at least) once a node is at version 1.0.0? If so, are developers discouraged, perhaps subconsciously, from releasing 1.0.0? Should there be some discussion of this in the Creating Nodes section of the documentation?

Can I start with version 0.0.1?
Many developers, including myself, have done this at times. Technically, this is a patch version, and development should start with 0.1.0. Does anyone care?

Do I need to worry about (or document) which versions of Node-RED or node.js my node has been tested against? Do I need to be concerned that my node might be broken by new major versions of libraries that are loaded by NR or other nodes and that I am using implicitly, without a dependency declared in the package.json?

Other tiny questions are not worth listing, but may appear if anyone responds.

[Colin]

@drmibell

When should I release version 1.0.0

My take would be to go to 1.0.0 once you think you have it working with a stable spec and are reasonably confident you won't have to introduce any breaking changes for some time.

As for why so many nodes are still 0.x.x I suspect that is mostly because the author just never got round to saying ok, that's it, release v1.

@drmibell

Can I start with version 0.0.1

It doesn't matter really. Strictly I suppose it should be 0.0.0, but I must confess I tend to start with 0.1.0, just because it sounds better I think

@drmibell

other nodes and that I am using implicitly, without a dependency declared in the package.json

Don't they all have to be declared in package.json. I think you should use there entries like
"fs-extra": "^4.0.2"
which means at least 4.0.2 but less than 5.0.0 so you allow non-breaking updates to the module.

Don't know about the node-red/nodejs question, will be interested in the answers.

[BartButenaers]

Hi Mike,

@drmibell

I hesitate to think of 0.x.y as a red flag telling me to avoid using a node until it is stable

Then you will need to ignore a bunch of my nodes, because in the beginning I wasn't aware that semantic versioning was so important for some folks. First time I heard about it, was Nick explaining at the time being why he wanted to get the 1.x version ready. So lots of my nodes still have a 0.x version...

@drmibell

Do I need to worry about (or document) which versions of Node-RED or node.js my node has been tested against

Testing my nodes on multiple Node-RED/Nodejs versions is not a service that I can offer for my nodes in my limited spare time. If somebody has a problem with one of my nodes, I expect them to report it clearly, and I will try to fix it. That is the least that I expect from users that are allowed to use my developments and support for free. After all, it is only a hobby for lots of us. So no compatibility charts for my nodes...

Bart

[TotallyInformation]

@drmibell

On the other hand, do NR users expect a certain level of support (bug fixes, at least) once a node is at version 1.0.0? If so, are developers discouraged, perhaps subconsciously, from releasing 1.0.0?

I would tend not to release a v1 until I'm sure that it really is a sensible node and reasonably stable. But I think I tend to get to a point where I've put in a lot of work and content to a node and end up thinking - Hmm, if I change to v1 now, people will expect a breaking change. So a bit self-defeating all round

@drmibell

Technically, this is a patch version, and development should start with 0.1.0. Does anyone care?

Nope It just feels wrong to start with v0.0.0! But now you've mentioned in, perhaps I'll start my next node with 0.1.0.

@drmibell

Do I need to worry about (or document) which versions of Node-RED or node.js my node has been tested against?

Yes. But probably not as much as some other platforms. At the very least, you need to say the minimum supported version of node.js and Node-RED. The package.json file is used for that of course.

@drmibell

Do I need to be concerned that my node might be broken by new major versions of libraries that are loaded by NR

Of course, that is always a concern and the reason for having major versions in semver of course. But, any node you write should have explicit entries for dependencies so generally, npm will sort that out for you.

@drmibell

that I am using implicitly, without a dependency declared in the package.json?

No, no, no! Don't do that. Ever.

[dceejay]

@drmibell

Do I need to worry about (or document) which versions of Node-RED or node.js my node has been tested against

Currently Node-RED still supports back to node8. So yes you should probably note if you require a minimum level higher than that or add a minimum engines level in your package.json.

[Nodi.Rubrum]

You could always use a versioning qualification established by someone else as a model. https://en.wikipedia.org/wiki/Software_versioning. On the wiki, Microsoft method versus Apple method is compared for example.