Introduction
I had always wanted to contribute to a large open-source project like Node.js but found it daunting to find a place to start. One day while playing with N-API native addons, I finally found somewhere to contribute. My addon required me to create and check Date objects though that functionality appeared missing from N-API.
What is N-API?
N-API allows developers to write native addons to Node.js in C or C++
The Node.js documentation describes N-API as follows.
N-API (pronounced N as in the letter, followed by API) is an API for building native Addons. It is independent from the underlying JavaScript runtime (for example, V8) and is maintained as part of Node.js itself. This API will be Application Binary Interface (ABI) stable across versions of Node.js. It is intended to insulate Addons from changes in the underlying JavaScript engine and allow modules compiled for one major version to run on later major versions of Node.js without recompilation.
The N-API is a C API that ensures ABI stability across Node.js versions and different compiler levels. A C++ API can be easier to use. To support using C++, the project maintains a C++ wrapper module called node-addon-api. This wrapper provides an inlineable C++ API.
N-API Resource
A great introduction to building a native module using N-API and the node-addon-api C++ wrapper.
Preparation
The Node.js project has a great deal of documentation around the process of making and submitting a change. I started reading and preparing my local environment to add new code and run the unit tests. The following documents helped me to get started and follow the correct process.
CONTRIBUTING.md
Provides several links to the information needed to get set up and start working on your changes.
doc/guides/contributing/pull-requests.md
How to set up your local development environment, and the pull request process. Contains a wealth of information such as commit message guidelines and how to keep your branch in sync with upstream. I read this document many times during the process of making my changes.
BUILDING.md
How to generate a working build of Node.js and run the unit tests.
doc/guides/cpp-style-guide.md
Node.js C++ style guidelines, idioms and use of language features.
doc/guides/writing-tests.md
How to structure tests and how to write both JavaScript and C++ Unit tests.
src/README.md
Not needed for doing N-API work but contains detailed information on the C++ code at the core of the Node.js project.
I followed the steps outlined in the documentation to fork the project and get my branch building. I could then run the unit tests and begin adding the missing feature that I wanted to add.
Coding
I started looking at extending the N-API code to support the basics of the JavaScript Date object. I learned a lot from looking at other N-API JavaScript object implementations. Pull requests from others also provided help in understanding how everything worked.
I ended up adding three functions to allow usage of the Date object from N-API.
napi_create_date
This API allocates a JavaScript Date object.
napi_is_date
This API checks if the Object passed in is a date.
napi_get_date_value
This API returns the C double primitive of time value for the given JavaScript Date.
Also, I included JavaScript and C unit tests and documentation. Following the project documentation and existing implementations gave me a lot of inspiration.
Pull Request
doc/guides/collaborator-guide.md
Describes how Node.js collaborators will review your changes. I found this valuable to understand the process from the side of the reviewers.
I opened my pull request on February 4th, and it landed in master on February 28th as 13b1aaf. Feedback came quickly which made for a consistent and smooth process. You can see how the process went as the Node.js team reviewed my code and gave feedback and comments.
My change became a part of N-API version 4.
Node.js v11.11.0 contained my Date object addition to N-API. A later backport included it in v10.17.0
Experience
I learned a great deal during my experience and overcame the fear of contributing to larger open-source projects. I always looked up to and respected the Node.js members who reviewed my pull request. I had looked up to them like rock stars, having them review my code with welcoming professionalism made for a rewarding experience. Later that year while attending the Node+JS Interactive conference I had the chance to thank many of them in person.
I recommend that anyone who feels that they have something to contribute to any open-source project gives it a try. More often than not, project maintainers will provide guidance and work with you to land your changes.
Looking forward to landing more changes in Node.js core as soon as possible. I also hope everyone else can contribute to open-source projects where their expertise or area of interest takes them.
Top comments (4)
Nice :)
That said, it's not always that swift... For instance, I've created a pull request in Vuejs fixing an infinite loop bug in the template compiler (symptoms: compilation blocked indefinitely, 100% CPU usage... not something that can be ignored, I thought).
I had a hard time making my issue not being discarded, and two years later, the bug is still present, and the fix has not even been reviewed ever since.
I'm not being bitter, I actually dont care, but just to tell: Making yourself heard while contributing to large projects can also be a challenge, even (especially?) for small fixes 🤔 (I had other, less stereotypical, experiences).
I totally agree with this, I have also had a wide range of responses to Issues and PRs from different projects. I have seen everything from the good experiences with Node.js, to other projects where I get massive pushback on reasonable changes, to radio silence for years. A lot can depend on the project's governance style and how the maintainers see your specific issue.
You are correct that in larger projects it can be really tough to have your issue seen as important, especially if there is trouble reproducing it or a lack of community support behind it.
I appreciate this take on the Open Source world, thank you for adding your experiences.
Unrelated question: Have you used a perticular template for you blog ? (I'm looking into publishing one, and I like the simplicity of yours)
My Nested Quotes blog is built using 11ty static site generator and a custom template that I built using the Bulma CSS framework.
I looked for a long time to find something clean and simple and could never really find the right thing. Maybe when I have some time I will try to release it as a template and write up some info on how it was made.