Bringing the nodejs/help backlog down by 90% over 2 months, and best practice recommendations for raising issues Node.js Follow Jun 6, 2018 · 8 min read

This post is from Gireesh Punathil who is a Node.js Collaborator, and the Service Architect for IBM Runtime technologies. His work is focussed around improving Node.js user experience. It originally appeared here.

A little while back I noticed that there was a relatively large backlog of about 200 issues in the nodejs/help repo (while the main node.js/node repo issue tracker covers bugs and issues found within Node.js core, general support with Node.js is covered under this repo) and decided to see what I could do to help bring that number down.

With the high degree of collaboration and information exchange typical in the Node.js community, we were able to bring down the backlog from ~200 to ~20 in a span of 2 months!

While reflecting on that success, I want to share some of the observations from this effort that will help both Node.js end users or consumers as well as the Node.js community itself.

I hope to answer the following questions:

What are the most common types of issues reported?

What are the most common reasons for issues?

What are the most common paths to resolution?

What are the most common types of issues reported?

While the linked items are representatives of common issues, they are not necessarily in any particular order.

What are the most common reasons for issues?

Architecture: Code built with linear programming paradigm breaks in asynchronous flow. For example, a user complains regarding a particular code sequence being executed, or not being executed, which is unexpected for them.

User background: Code breaks due to incorrect perception about Node.js API abstractions. For example, a user has a program that closed the underlying descriptor of a Node.js stream through external means, and was expecting the stream to emit its lifecycle events.

Deployment models: Code breaks in untested (or unforeseen and mostly unsupported too) deployment environments. For example, some UDP capabilities are unavailable when transforming the Node.js source for a browser target.

Integration: Code breaks while trying to connect with heterogenous, polyglot endpoints. http , IPC , native addon , stream are layers that usually interact with polyglot endpoints, and because of the plurality of conventions that exist at the remote endpoints, inconsistency can arise due to incorrect usage.

, , , are layers that usually interact with polyglot endpoints, and because of the plurality of conventions that exist at the remote endpoints, inconsistency can arise due to incorrect usage. Documentation: Code does not behave according to written doc, or doc is not explicit

What are the most common paths to resolution?

Question answered and help provided to OP’s satisfaction. In many cases, a single crisp answer addresses the problem / question, though in a few cases, explanation with sample code and output was required. By far the most common case.

Revealed an issue / enhancement in Node.js (code or doc), fix provided. Rarely, the investigation reveals that it is a bug in the Node.js core, and that leads to a PR being raised and contributed to the project.

Revealed an issue / enhancement in Node.js (code or doc), OP contributes the fix! This is great, and the originator (and the community) really get excited about it.

Revealed an issue / requirement, but outside Node.js’s scope. This happens when the user’s stack involves Node.js, but the issue is not within Node.js’s purview. So this is referred elsewhere as appropriate. If it is something reusable but does not necessarily need to go into the core, user land modules (external reusable modules, mostly npm ) are developed.

) are developed. No longer a problem, fixed in latest Node.js releases. The recommendation here is to always try with the latest LTS release before you raise an issue. Many known issues are resolved in the latest release, and the LTS is the most mature release.

OP no longer interested in the support, or unavailable. This is a concern — for example a good amount of work would have been spent on problem determination by both parties, and when one side is unavailable for further progress or clarification, it causes a waste of time and effort.

Recommendations and Best practices

To get help and support by best leveraging the skill and collaboration among the community, I recommend the following best practices while opening / engaging on issues:

Concepts users should gain familiarity with

Understanding your application stack will help to identify whether the desired support is pertinent to Node.js or elsewhere in the ecosystem.

Understanding the execution environment of Node.js (asynchronous programming model with event driven architecture) will help quickly ratify some of the issues and make amendments accordingly. This is more important for users with other language / platform backgrounds.

While Node.js abstracts the underlying platform and provides a unified programmer experience, understanding any unique traits of your platform (path separators in Windows, I/O buffer size in Darwin, process-scheduling order in AIX etc.) will help you to isolate problems yourself.

How to raise an issue effectively

Fill out the issue template completely. If you don’t know what to provide in some fields, state so.

Present your problem clearly. Ideally, add a minimal test case to reproduce the problem, a statement that shows what is expected, and output that shows the actual result.

Detecting and reporting issues early in your development phase helps to reduce the amount of refactoring or redesigning of your application that may be required. These changes can be difficult to do later, depending on where the problem is and the resolution path that is identified.

Participation guidelines

Be available for clarifying any questions that may come up, and while debugging. Community members frequently do not have the same deployment scenario as you, so we depend on you for the problem determination! Issues get closed due to inactivity.

Use the Node.js API documentation; it’s content-rich as well as end-user focused. You might be able to solve many of your problems by referring to the doc.

While it is not enforced, it is much appreciated if you are willing to contribute to the project, if need be, based on the outcome.

Recommendations for collaborators working on these issues

Ask questions in the beginning about the execution environment in which the issue occurs, to help to isolate the problem context.

Many issue reports or help requests appear with few or no clues about the requirement, due to the background of the user: understanding about the problem, programming experience, interaction with community, language barriers etc. A couple of iterations will help to gain clarity and refine the problem scope.

Many users arrive in the nodejs/help repo through a notion of “general support for any issues while using the Node.js stack”. Often, we may need to direct users elsewhere, but provide some information on the relevant project area / repo / vendor to seek support with.

repo through a notion of “general support for any issues while using the Node.js stack”. Often, we may need to direct users elsewhere, but provide some information on the relevant project area / repo / vendor to seek support with. Often it is possible to represent the problem or the requirement in the form of a small test case. Writing one with the program output helps to quickly blow away many gray areas and ratify the understanding of the parties involved.

We use many methodologies for problem determination, and many tools to debug. Recording the diagnostic steps as well as the actual commands used helps users to relate to those methodologies and tools, and adopt them without further education.

Linking to other discussions that are related, linking to the source code blocks that are relevant, and quoting the documentation that supports the statement helps users to figure out how and where to look for information for future problems.

Copy known experts and SMEs in the community if you need deeper and/or design-level discussion. Collective intelligence is the most notable advantage in an open source project.

Finally, focusing on the problem statement (the engineering side of the collaboration) alleviates frictions or shortcomings on the social side, and helps to conclude the work item with a high level of constructive engagement.

Summary

Keeping the issue backlog within a reasonable threshold is a key characteristic of a healthy community and the ecosystem that flourishes around it. I request consumers and contributors of this repository to engage in a meaningful, timely, and constructive manner for resolving identified usage pain points, making sure that the design follows the documented behavior, and leveraging this engagement for identifying potential enhancements to the core for its future roadmaps — mid-term and long-term.

Looking to contribute to the Node.js project?