Node.js Package Maintenance: Bridging the gap between maintainers and consumers

This blog was written by Michael Dawson with input from the Node.js package Maintenance Working Group. It was originally posted on the Node.js blog. Node.js is an OpenJS Foundation Impact Project.

A while back I talked about the formation of the Node.js package maintenance Working Group and some of the initial steps that we had in mind in terms of helping to move the ecosystem forward. You can read up on that here if you’d like:
https://medium.com/@nodejs/call-to-action-accelerating-node-js-growth-e4862bee2919.

This blog is a call to action for package maintainers in order to help in one of our initiatives and to move it forward, we need your help.

It’s been almost 2 years and we’ve been working on a number of initiatives which you can learn more about through the issues in the package-maintenance repo. Things never move quite as fast as we’d like, but we are making progress on a number of different areas.

One area that we identified was:

Building and documenting guidance, tools and processes that businesses can use to identify packages on which they depend, and then to use this information to be able to build a business case that supports their organization and developers helping to maintain those packages.

We started by looking at how to close the gap between maintainers and consumers in terms of expectations. Mismatched expectations can often be a source of friction and by providing a way to communicate the level of support behind a package we believe we can:

• help maintainers communicate the level of support they can/want to provide, which versions of Node.js they plan to support going forward, and the current level backing in place to help keep development of the package moving forward.
• reduce potential friction due to mismatched expectations between module maintainers and consumers
• help consumers better understand the packages they depend on so that they can improve their planning and manage risk.

In terms of managing risk we hope that by helping consumers better understand the key packages they depend on, it will encourage them to support these packages in one or more ways:

• encouraging their employees to help with the ongoing maintenance
• provide funding to the existing maintainers
• support the Foundation the packages are part of (for example the OpenJS Foundation)

After discussion at one of the Node.js Collaborator Summits where there was good support for the concept, the team has worked to define some additional metadata in the package.json in order to allow maintainers to communicate this information.

The detailed specification for this data can be found in: https://github.com/nodejs/package-maintenance/blob/master/docs/PACKAGE-SUPPORT.md.

The TL/DR version is that it allows the maintainer to communicate:

• target: the platform versions that the package maintainer aims to support. This is different from then existing engines field in that expresses a higher level intent like current LTS version for which the specific versions can change over time.
• response: how quickly the maintainer chooses to, or is able to, respond to issues and contacts for that level of support
• backing: how the project is supported, and how consumers can help support the project.

We completed the specification a while ago, but before asking maintainers to start adding the support information we wanted to provide some tooling to help validate that the information added was complete and valid. We’ve just finished the version of that tool which is called support.

The tool currently offers two commands which can be used which are:

• show
• validate

The show commands displays a simple tree of the packages for an application and the raw support information for those packages. Much more sophisticated commands will make sense to help consumers review/understand the support info but at this point it’s more important to start to have the information filled in, as that is needed before more sophisticated analysis makes sense.

The validate command helps maintainers validate that they’ve added/defined the support information correctly. If there are errors or omissions it will let the maintainer know so that as support information is added it is high quality and complete.

Our call to action is for package maintainers to:

• Review the support specification and give us your feedback if you have suggestions/comments.
• Add support info to your package
• Use the support tool in order to validate the support info and give us feedback on the tool
• Let us know when you’ve added support info so that we can keep track of how well we are doing in terms of the ecosystem supporting the initiative, as well as knowing which real-world packages we can use/reference when building additional functionality into the support tool.

We hope to see the ecosystem start to provide this information and look forward to seeing what tooling people (including the package-maintenance working group and others) come up with to help achieve the goals outlined.