Improving the Node Ecosystem

[sammachin]

The node-red ecosystem is now 7 years old and in that time over 3000 node packages have been published to the catalog. Over time this has led to a certain amount of ‘cruft’ within the catalog as packages have become abandoned by their authors, API’s have changed and the platform has evolved.
This in turn has led to frustration for both developers who have wanted to contribute fixes to nodes but because the developer has not responded, generally this results in a forked package with a similar name and more cruft in the ecosystem.
Users then find it difficult to to identify which is the ‘best’ package to meet their needs further causing frustration both for the user and the developer of the newer maintained packaged that they can’t stand out from the older outdated package.
Node-RED relies on the npm platform to underpin our package management therefore to some extent we are limited by the constraints of that and the existing legacy packages, however the following proposals are intended to to work within those confines to address some of the issues and over time improve the general health of the ecosystem.

We also recognise that there are a large number of developers that create and publish nodes primarily for their own use and enjoyment, we do not want to put additional barriers in place that discourage these contributions, therefore we are committed to maintaining the ability to publish to NPM and get listed in the catalog as it stands today, All proposed changes to the ecosystem are intended to be optional additions rather than any additional burden.
This does mean that potentially some developers may find that their nodes are less discoverable than others, but we commit to keeping the ability to enter a package name into the palette manager and then install from there as it is today.

The recent survey highlighted a issues in a several areas: Duplication, Compatibility, Naming, & Forking.

The following proposed changes are designed to address some of these issues and overtime to improve the overall quality of nodes in the catalog resulting in a better experience for developers and users. Some of this will take time to show an impact as we won’t require existing nodes to update just to make the changes but hopefully as new nodes are published and updates are released we will see a gradual improvement.

[sammachin]

Flows page embedded within editor

The first and possibly largest change is to bring the flow.nodered.org pages into the node-red editor itself. Today a user can link out to the page clicking the fa-external-link item in the palette, however when browsing a number of nodes to try and find the best fit this can result in opening a lot of tabs and makes it harder to follow where you are.
I propose that his link should open a new modal window on the editor which embeds the page from flows.nodered.org with just just centre content section (no header, footer, search bar)

This will improve the user experience of finding the right node as today the readme page in the package generally provides the most comprehensive overview of a nodes capabilities, it will also serve as a basis for making future changes to the experience around rating, certification etc. within the flows.nodered.org site without having to make changes to the node-red editor itself.

The other thing that should be considered is if the current external link icon is sufficiently visible to the user or if this should be moved to a button like the install button labeled view or similar.

need an option to switch back from modal to new window in settings
How to handle custom catalogs without webpages (don’t show button)

[tve]

I find that a lot of nodes don't have a great front-page. Maybe that already says something... But I almost always need to click through to the github repo to figure out whether this node is for me or not. If you implement this modal window you need to consider the workflow when clicking the "view on github" link. E.g., open in modal? open in same tab? open in new tab? How did the modal help in the first place?

[sammachin]

Naming

The current convention is for community nodes to use a package name with a prefix of node-red-contrib-
This worked well in the early days when trying to differentiate between nodes created by the core project and those by the community, however the catalog is now over 95% made up of community nodes so this labelling has lost much of its impact.
In addition users have commented that all nodes having the same prefix which makes up the majority of the name makes reading a list of nodes confusing.
Another issue with naming is forking, often nodes that are abandoned by their original developers and a new developer wants to make fixes or improvements, they are forced to fork the node and publish under a new name. This is partly both a problem and a feature of the way npm works in that once a package namespace has been created its difficult for another person to take that over, this serves to protect against various security issues.
However when forking a node it also creates problems for the user to figure out which is the ‘best’ or latest fork of a node, or even if there are forks or just 2 totally different nodes with similar names.
The proposal is to encourage developers to publish their nodes within scopes on npm, and to revisit the naming convention to remove the duplicated prefixes, for example instead of a developer called AcidBurn publishing a package named node-red-contrib-risk tools they would publish it as @AcidBurn/risctools-nodered
Within the palette manager and the flows pages we could then use just the package name so that users can more easily read a list, things like alphabetical searching becomes easier because the main function/service of the package is first and then the scope/developer name can be shown separately.
In addition this makes forks easier to manage as if AcidBurn decides to abandon their risctools node and later ZeroCool wants to publish some fixes they can publish a new package named @ZeroCool/risctools-nodered.
Within the palette manager we could then start to associate nodes with the same name but different scopes as being related/forks.
Nodes from the core project would be released under the @nodered scope.
Consideration needs to be given to how existing nodes could be migrated to this as it would prevent current users from upgrading if the package was republished under a scope, perhaps it should only be done as part of a major version change?

[TotallyInformation]

Not entirely convinced this will work. The association of same-name/different-scope is a nice idea but is entirely dependent on people following a naming convention. That would need to be taken into account. How would the library manage badly named packages?

Also, I would be against a wholesale change in the way node packages are named. At the least, the existing naming needs to be supported as many of the best nodes have that naming and it would be very confusing for people, especially those who only use Node-RED occasionally, to suddenly find their long-familiar nodes have changed name drastically.

In addition, asking developers to wholesale change their package names just to fit this new scheme is a little unrealistic as most of us barely have the time to develop at all. For someone like Bart, this would be a bit of a nightmare.

I think that, if you wanted to begin a process of dropping the long prefix, you would need to ensure that names with and without the prefix could be matched in the library. A similar process could then also be used to match nodes that are very similar but with differing names.

You are very likely to also need an arbitration process as well in case of naming disputes. It would be sensible to introduce this anyway now that we have so many nodes, eventually it is likely that we have a bad actor or someone with less than perfect judgement causing an issue.

One final point, not that this should really be a negative against this proposal, personally I find the who area of scopes really confusing. The link between the repo and the npm scope is not clear. I also find it incredibly hard to find code within the node-red scope because it isn't clear how the scoped package name relates to the repo name. While this might just be me, I can't help feeling that many others will be confused as well. We will need some good documentation to help with this aspect I think.

[sammachin]

The current configuration of flows.nodered.org doesn't impose any naming requirements for stuff to show up in the catalog anyway its just down to conventions. The catalog is no longer auto-updated from npm a developer is required to login and submit a package for inclusion or updates. The only check we perform for listing is that the package.json has node-red listed in its keywords.
There are some packages today that are using scoped names, you can see a pretty good example if you search for the term 'CPU' this will bring up 2 versions of node-red-contrib-os one of which is scoped along with a couple of other packages with CPI in either the name or description string.
All that is being proposed here is to change the guidance that currently tells people to use node-red-contrib- as a prefix to being "Use scopes and optionally you can use the string nodered in your package name.

The aribtration process is actually an interesting point scopes are part of the solution here within the npm ecosystem because the scope is only avalible to an organisation/user to publish under, think of it much like a domain name. So by carving out the package namespace in this way it keeps a clean separation between developers. Today its first come first served on package names and this does mean that for node-red there are useful names that have gone and sometimes are being blocked by an abandoned package.

There's not really any connection between a repo and a scope or for that matter between a package and a scope,
Repos are just a way of publishing source code, and GitHub is the most common, within those there is a concept of a username (person/org) and then a repo name
NPM is a package manager where users publish a zipped tar archive of their code as a release, within NPM you have a username which is also your scope again for a peson or org and then packages can be published, the confusion comes because originally NPM didn't have scopes so all packages were under a 'global' scope and then scopes were introduced in version 2.
Things are further confused because there isn't even always a 1-1 relationship between code repos and packages, for example the repoistiory at github.com/node-red/node-red holds code that is published as 2 different pacakges on NPM the main node-red package and the nodes in @node-red/nodes as you can see one of those is scoped the other isn't!
There's no requirement for a package on NPM to have its code published in any repository and the namespace for users/orgs/scopes are not connected other than by convention, most users will choose the same username on different sites.

[TotallyInformation]

the scope is only avalible to an organisation/user to publish under, think of it much like a domain name

Yes, I get that. But what happens if @somenaughtyperson/uibuilder is published that has nothing to do with node-red-contrib-uibuilder? That is when you need some arbitration. uibuilder is a well established name in the Node-RED ecosystem as is Dashboard and any number of well established nodes.

There's not really any connection between a repo and a scope or for that matter between a package and a scope,

Yes, that is what I find very confusing 😊 How do we make this clearer to people? At the moment, it is pretty simple for someone looking at the node-red-contrib-uibuilder npm package to see that it relates to a specific repo in GitHub. They can easily view the source code, documentation, WIKI, etc. But for Node-RED core and core nodes, I never know where to look and I always have to dig around. Yes, this is my lack of experience with scopes, I know that, but it illustrates the issue a lot of non-pro Node.js programmers will face. All I'm saying is that the use of scopes adds (significant) complexity and that at least deserves some good documentation to steer less experienced people if we want to keep people on-board and encouraged to participate. Lets not accidentally loose the heart of what has made Node-RED such an approachable success.

[knolleary]

Yes, that is what I find very confusing 😊 How do we make this clearer to people? At the moment, it is pretty simple for someone looking at the node-red-contrib-uibuilder npm package to see that it relates to a specific repo in GitHub. They can easily view the source code, documentation, WIKI, etc.

As long as the package.json has the repo entry, we will link to it on the flow page. The presence of a scope doesn't change that at all - in fact it directly addresses your concern by giving the definitive link between module and repo.

Scopes exist to solve the namespace problem. Just because you aren't familiar with them, doesn't mean they aren't something for us to consider recommending.

Of course any change to our recommend approach to naming will be accompanied with good docs and explanations as to what scopes are.

I don't see any path to us changing/republishing nodes under any new naming scheme. This is about recommendations for new nodes moving forwards. Depending on the outcome of the discussion, some node owners may choose to rename their modules - and we will have to provide clear docs on how to do that as well as the impact it will have on end users (being clear there would be no expectation or requirement to change names).

[TotallyInformation]

Just because you aren't familiar with them, doesn't mean they aren't something for us to consider recommending.

Of course! However, it is something that should be addressed in documentation. I get the reasoning for them and even though it seems to me to be a horrible kludge (poor architecural thinking in the npm project), it does get the job done. So I'm not suggesting you shouldn't use them, just explain the concept to users.

I don't see any path to us changing/republishing nodes under any new naming scheme. This is about recommendations for new nodes moving forwards. Depending on the outcome of the discussion, some node owners may choose to rename their modules - and we will have to provide clear docs on how to do that as well as the impact it will have on end users (being clear there would be no expectation or requirement to change names).

I didn't think otherwise but wanted it to be clear.

[sammachin]

Examples

Today very few packages include example flows, and for those that do very few users think or know where to look to load the examples.
It is more common for an example flow to be included in the README as a blog of json.

We need to raise the awareness of examples:

• Where a package includes examples then a button/link should be in the node-red-help section within the node
• Add info about examples to flow library page.
• The example section should be created as part of a scaffold/example node to encourage developers to include that
• Any future certified/rated nodes system should require packages to include examples as part of the approval process

Where examples are included in the README we should start making PR’s against the nodes to move those into an examples folder, This could be something to promote for Hacktoberfest?

[sammachin]

Lifecycle

Once a package has been added to the catalog there is currently no easy way for a developer to manage its lifecycle, it is proposed to add 2 new actions for a logged in owner of a package:

Deprecate

This will mark a package as deprecated showing that the developer no longer intends to maintain it with updates or support. The developer will be asked to add an optional message that will be shown on the catalog page, perhaps recommending an alternative or even just to ask for a new owner to take over.

Remove

This will remove a node from the catalog, It does not remove the node from NPM (as this generally isn’t possible) so existing users with the node installed will still be able to update or rebuild their instances, however it will not show up in the palette manager or on the flows.nodered.org pages.
It would still be possible for a user to manually install the package through the npm install cli but this is outside the scope.

Should we auto remove nodes after a fixed time of deprecation, eg 1 year??

Report

The report button is on the site today but only availble to logged in users and generally it is intended for flagging objectionable content. We could look to expand this use to have users flag nodes which appear to be abandoned and then consider marking them as deprecated.
It should be highlighted to the user when the click the report button that this is not a channel to request support on a node or simply if they find a bug in a node it is only to be used where a node appears abandoned and they have attempted to contact the developer - wording needs to be thought through.

[juggledad]

Should we auto remove nodes after a fixed time of deprecation, eg 1 year??

Anyway to check if there are open issues? I.e. If node hasn't been updated in a year but there are no open issues with it, it could still be good. If it has open issues then it goes into depreciation status. If after a another year it still has open issues, then it is unlisted.

I wonder if you could tie in downloads. Mayve a node is solid and hasn't been updated in 3 years, but is being downloaded many times a day. That would seem eto indicate it is still a good node - but it would be good for the author to do some kind of 'touch' to the node to indicate the node is active and the author is still active/alive....

[sammachin]

@juggledad In this scenario I was thinking about nodes that are explicitly marked as deprecated by the developer being removed after a set period. The kind of things you're thinking about are probabbly better covered in the scorecard section below

[TotallyInformation]

THe idea of auto-remove is, of course, inviting. However, it ignores the fact that there are cases where nodes do not NEED to be updated. Perhaps they are relatively simple or are for interfaces that are highly stable.

An old node isn't necessarily a bad node.

[sammachin]

@TotallyInformation In this context I was only referring to nodes that had been marked as deprecated for a year, so a node thats still ticking along would never get marked as deprecated and therefore not removed.

[sammachin]

Support

An issue that was raised by both users and developers is around support for nodes. While github issues work well for some people many users don’t have github accounts and it`s not always an obvious path to get from a node in the editor to the appropriate github repo.
Many users said that the forum provides a good support channel, often questions are answered by other members of the community rather than the nodes original creator. However it was also felt that there is a large amount of hidden knowledge within the forum history and it is not easy to see if someone has previously asked the same question around a node.
Some developers commented that they are not always active on the forum so often don’t know that users are posting there regarding their nodes.

The following changes should help to address this:

• Add package names as tags in discourse
• Use these tagged posts to indicate questions on the flows.nodered.org page (either a number of posts or import a list of topics)
• Display the number of GitHub issues a project has, both open and closed. Again either a number or a list depending on design.

In addition having posts in the forum tagged with the relevant nodes would open up the possibility for developers to signup to be emailed when a post with their node-tag is created, this could form part of a certification/rated nodes programme in the future.

[sammachin]

We have started to experiement with tagging on discourse, for now tagging is enabled and moderators can manually create new tags as questions around nodes appear, This avoids filling up discourse with 3000+ tags most of which won't be used.

[TotallyInformation]

It would be really helpful to be able to tag uibuilder posts - is there a process to get started?

[sammachin]

@TotallyInformation I've added node-red-contrib-uibuilder as a tag, the tag can be added to a new topic on discourse when its created, (dropdown next to the category) or users with permission to edit the title/category etc can also add the tag to a post. I think you have that level.

[TotallyInformation]

Many thanks. I've just added it to an ongoing thread 😊

[sammachin]

Certification Scorecard

The survey asked what users and developers thought of having some nodes be “certified” we didn’t give any details of what this might involve as its stil at the early idea stage.
In general users were in favor of having certified nodes to as it would improve the discoverability, there was some hesitancy especially if this was the only metric, it was felt that it should be combined with community mechanisms such as reviews. There was a desire to be able to see which versions of NodeRED a node is compatible with (is this an issue other than NR1.x 2.x> ) along with identifying any security issues with the dependencies.
It was felt that it should be a time limited feature so that nodes must re-certify to indicate they are still current.
There was a concern that a one size fits all approach might not be helpful as comparing a simple logic type node with a complex API client dont have the same requirements.
Developers were understandably slightly more hesitant of certifcaiton, key points were;
That it must be optional and not a requirement to appear in the catalog, That it must be free, it should help developers to improve their nodes by giving actionable feedback rather than just “pass/fail”, It should be an automated process that developers can run against their packages locally. Needs to take account of the wide variety of nodes in the ecosystem.
There was also comments from both users and developers that it would be good to identify “Official” nodes from the companies behind certain platforms and services, although this is separate from certification.

To this end I am proposing the following:
Rather than a single certified check mark we use a scorecard that lists out various checks on a node and then the results, This will make it clearer to users what a node does or does not have along with making it clearer to developers where they can improve their nodes to boost their score.
The overall scorecard will then be summarised with a single value either as a percentage of checks passed or perhaps as a grade A-F, (it should not be a number 1-5 or starts so as to distinguish from the community rating)
The scorecard will show the date of the last review and the version number reviewed, nodes that do not re-submit every ?12 months will show their rating as expired.
The exact details of the checks should be developed with the community and it is likely over time that they will evolve to include deeper checks. - We need to keep some stability in order for ratings to be consistent, perhaps an annual review of the tests?
As part of submitting a node for scoring the developer will also be able to register an email address that they would like to be notified of various things on, for example alerts to tagged posts on the forum, dependency issues, new node red versions, and platform news.
This should help to provide developers with an incentive to submit their nodes.
A version of the scoring tool could be offered as a CLI (plugin to node-red admin?) so that developers can run the checks locally and see the results along with suggestions for how to fix/improve. The final scoring will be run on the flows.nodered.org site.

[TotallyInformation]

Two things that really do need to be exposed in the catalogue I think and that would really help people decide if a node was useful to them would be the node.js and node-red version indicators in the package.json. In addition, number of downloads in a week isn't a terribly good metric, I think it would be better to at least have it over a month.

[sammachin]

Good point on the nodejs versions, I don't think many packages declare it today in their package.json but its something we can add as a check to the scorecard and then indicate, we do need to watch out for nodes that declare a fixed version of node eg "node": "14.x.x" as these would then fail to work on future versions like node 16, its just something to explain in the docs and warn about in our validator I think.

I wonder where how best to declare a min node-red version @knolleary do you think it could be put in the engines section of package.json? or would it be better in the custom node-red section. For now I don't see us doing any validation at install time but we could display it on the scorecard and it gives us a potential for future checks if a major version introduces breaking changes.

I htink the overiding aim here should be to allow developers to indicate which versions they have built their package agasint and then to inform users of this, however we should be very careful about enforcing and kind of version checks as I think the risk of a good node being locked out by an updated node or node-red pacakge is greater than the risk of it failing and expecting developers to update their compatibilty on new version releases isn't practical.

[meeki007]

I like the score-card Idea. As checks are added the Grading system could even go (A-)(B+)(etc)
If and when you need a testing guinea pig let me know. I have a old contrib that works but is missing done/close for node ver 0.17+ and 1.0+. a example section and other requirements your looking to implement.

[tve]

It seems to me that the scorecard idea is very closely related to the badges found on github. When you look at github projects, which badges are meaningful to you? That might give an idea about what might be useful to include for node-red.
For me, I look for badges around automated testing and test coverage primarily.

[TotallyInformation]

Meaningful badges:

• How many outstanding issues
• Code quality/Deepscan
• Number of stars/watchers
• Downloads per month
• Nodejs version

[TotallyInformation]

we do need to watch out for nodes that declare a fixed version of node

I don't think you need the process to think about that. Yes, lets put something in the docs but the responsibility belongs with the author.

how best to declare a min node-red version

This already exists doesn't it. I've always used the following in package.json:

  "node-red": {
    "version": ">=1.3.0",
    "nodes": {
      "uibuilder": "nodes/uibuilder.js"
    },
  },

very careful about enforcing

Agree. Even node.js itself backed off from this. A warning is sufficient.

[TotallyInformation]

Sorry, this was meant to be a reply the other thread. Not sure what went wrong.