Introducing Node Scorecards and a new node naming convention

News
1

We've just published a new post to the blog with a couple important updates for the Node-RED community.

I won't repeat the whole post here, but here are the key points:

  1. We've introduced Node Scorecards on the Flow Library - these provide an overview of how well a node follows best practices. It's primarily focussed on packaging at this stage, but can be expanded to other areas in the future. Scorecards are generated when nodes are updated on the flow library and we've been running it in the background for a couple months - so all recently updated nodes will have scorecards. They are linked to from the sidebar of the node's page. You can see an example scorecard here.

  2. We've updated our naming convention for newly published nodes. We now recommend nodes to use a scoped name (like @myScope/node-red-sample). This will helps address a number of usability issues with the node-red-contrib- prefix we've used to date. As well as what is said in the blog post, the documentation has been updated to match.

  3. node-red-dev has been published which is the command-line tool that generates the scorecard. This lets you generate the scorecard locally whilst developing a node. In the future, this tool could be expanded with other tasks to help node authors.

Please read the blog post for the full details.

7 Likes
3

Nice work.

One minor issue running against uibuilder vNext, looks like the node parser can't cope with the alternate layout for the .js file right now.

C:\src\node-red-contrib-uibuilder [vNext ≡ +1 ~4 -0 !]
> node-red-dev validate
    ---Validating Package---
   node-red-contrib-uibuilder@5.0.0-dev
✅ Package is Apache-2.0 licensed
✅ Repository/Bugs Link Supplied
 »   Warning: P04 New Packages should use a scoped name
✅ Package uses a valid name
✅ No similar named packages found
✅ Node-RED Keyword Found
✅ Compatible with Node-RED v2.2.0
✅ Compatible with Node-RED v1.3.7
 »   Warning: P07 Minimum Node version is not compatible with minimum supported Node-RED Version Node v12.0.0
    ---Validating Nodes---
Unable to parse  nodes/uibuilder.js
Unable to parse  nodes/uib-sender.js
Unable to parse  nodes/uib-cache.js
✅ Nodes all have unique names
✅ Examples found for all nodes
    ---Validating Dependencies---
 »   Warning: D01 Package has a large number of dependencies (14)
> ✅ No incompatible packages found in dependency tree
 »   Warning: D03 execa is not at latest version, package.json specifies: ^5.1.1, latest is: 6.0.0
Complete

Similarly on the wiser nodes:

C:\src\node-red-contrib-drayton-wiser [main ≡ +4 ~4 -0 !]
> node-red-dev validate
    ---Validating Package---
   @totallyinformation/node-red-contrib-drayton-wiser@0.0.3
✅ Package is Apache-2.0 licensed
✅ Repository/Bugs Link Supplied
✅ Package uses a Scoped Name
✅ Package uses a Scoped Name
✅ No similar named packages found
✅ Node-RED Keyword Found
✅ Compatible with Node-RED v2.2.0
 »   Warning: P06 NOT Compatible with Node-RED v1.3.7
 »   Warning: P07 Minimum Node version is not compatible with minimum supported Node-RED Version Node v12.0.0
    ---Validating Nodes---
Unable to parse  nodes/wiser.js
Unable to parse  nodes/wiser-listen.js
✅ Nodes all have unique names
 »   Warning: No examples found
    ---Validating Dependencies---
✅ Package has 5 dependencies
could not find a satisfactory version for string github:totallyinformation/ti-common-event-handler
✅ No incompatible packages found in dependency tree
✅ All prod dependencies using latest versions
Complete

Re the minimum node warning - it would, I think, be better to show what node-red requires and what the node requires? While I know, if that is also shown in the flows library, other people wouldn't know what the difference was. In the case of my newer nodes, the difference is that I have a minimum node.js version of 12.20 as there are a number of bug fixes and some revisions in that version that would probably be needed by the code in the nodes.

Also, the flow entry for the wiser nodes show:

image

But the package.json certainly has it:

image

UPDATE: re Unable to parse in checks.

Checking the code, it appears that only the .html is actually checked, not the .js file so my assumption was wrong. The reason the checkNodes funtion is struggling is that my .html files do not have type="...." on the javascript script tag - this is correct for HTML v5.

checknodes.js - node-red/node-red-dev-cli - GitHub1s

/<script.+?type=['"]text\/javascript['"].*?>([\S\s]*?)<\/script>/ig

From MDN:

The HTML5 specification urges authors to omit the attribute rather than provide a redundant MIME type.

1 Like
4

This is helpful for getting missing info for any of your own node or others as well.

5

I was also going to raise the node version warning being inaccurate.
I am also getting the below - despite having entries for both node and npm

image
image952×109 12.6 KB

6

Please raise an issue here: GitHub - node-red/node-red-dev-cli: Command-line tool for Node-RED Node authors

7

Exactly what I was doing :+1:

8

Although I check the flows site, I usually install nodes via the palette, will the scorecard eventually also arrive in the UI ? Especially with version dependencies it can help reduce issues that we often see in the forums (installing old nodes etc).

9

Yes, we are thinking about how to extend the catalog format to include extra information about the modules.

10

As a somewhat inexperienced developer, I've updated my nodes to reflect the new guidelines. In doing this, I added minimum Node-red and node versions to my "package.json" (just kinda guessed???). However, the question crossed my mind, how can I know what versions to put? Do I need to familiarize myself with the version history and changes of both of these projects or is there an easier way?

11

I started to read up on this via the link you shared @knolleary and found the link to "Flow Library" [text in red] on this page does not work. Is that intentional?

image
image772×226 22.8 KB

12

No. It was not my intention to have a broken link in the post.

13

Poor choice of words early in the morning :slight_smile:

14

I read "Introducing Node Scarecrow" at first :rofl:

Great work!

15

In general, it is best to use a node.js versions that matches the versions required by the version of Node-RED you have chosen. Choosing the node-red version is slightly tricky and I would suggest that yes, you may need to be aware of the changes.

In general, Node-RED supports the currently long-term supported versions of Node.js so of course that changes over time.

16

BTW if you work on the Palette it would be great to have the link to the flow library page for installed nodes present (same as on the install tab) to take a look into any release nodes (to avoid any surprises due to breaking changes before hitting the update button)
image

image
(currently you have to switch to flows.node-red.org or to the install tab and search for the node you plan to update)

A kind of warning system for breaking changes or a structured release nodes system (like a release-nodes.md file available in a drop-down right in the palette dialog) would be nice.

2 Likes
17

Is it OK to use the node-red-contrib- naming under a scope (as in @myScope/node-red-contrib-sample)? I would think so, as per the documentation:

If you use a scoped name, there are no further requirements on the name.

We just published our first couple of nodes as @myScope/node-red-contrib-, and it just seems tidier (for lack of a better word) to keep using the same naming convention for our future nodes.

18

Yes it is.

19

Excellent. Thanks for the quick response!

20

Is it kosher (or maybe even advisable) to publish a new version of a node "just" to improve the scorecard? On the one hand, it seems kinda spammy to publish a new release without so much as a bug fix, but on the other hand, providing better information to users could also be called a feature.