How to start contributing in NodeJS?

Hi there! Some of you want to or thought about contributing into NodeJS core but don’t know how to do it or don’t have enough confidence. Well, I’ll try to help you out with that.

I am an outside collaborator in NodeJS and sometimes I look into issues and take some. Also, I already have a few pull requests successfully landed into NodeJS core, so I’m going to tell you about my experience.

Let’s start with running it locally.

Cloning the repository

The first thing you must to do is fork the repository to your account.

Afterwards, you must to clone the source code of the NodeJS repository to your host machine from the fork.

At this step, you have two remotes: origin is for your fork and upstream is for NodeJS original repository. BTW, upstream still need to be added by you manually. To do this, add upstream via git remote in your project folder.

~/node: git remote add upstream git@github.com:nodejs/node.git

You should have two remotes now, you can check it like this:

~/node: git remote -v
origin git@github.com:ghaiklor/node.git (fetch)
origin git@github.com:ghaiklor/node.git (push)
upstream git@github.com:nodejs/node.git (fetch)
upstream git@github.com:nodejs/node.git (push)

Now, let’s compile, so you can run it.

Compiling NodeJS

Thanks to NodeJS contributors, we have scripts that you can call and compile easily.

~/node: ./configure
~/node: make

./configure scripts configures all the needed files for compilation. make compiles all the needed sources. As a result, you will get compiled binary in the same folder called node. Basically, it’s just a symlink to out/Release/node.

You can test it out and check if everything goes well:

~/node: ./node -v

It should print current version of NodeJS.

That’s it with compiling, nothing else. Now, let’s say you take some issue and want to try and fix it. What to do next?

Fixing the issue

Imagine, you take issue #1234.

First of all, create a branch for it from master branch:

~/node: git checkout -b fix/1234 master

Naming conventions can be different, but I’m using the following format: <TYPE>/<NUMBER>. For instance, fix/1234, feature/5678 and so on. Think of it as you have folders and files in it.

Ok, you have a branch for your fix and you have made some changes. BTW, it’s worth to note, that you MUST try to modify as few lines as you can. If you have changed some line just because of wrong space indent, the most of the time it will not go through a code review. Remember this.

After some time, you finally fixed the issue locally, great. You have done a few commits in branch fix/1234.

~/node: git commit -m "repl: describe the fix here"
~/node: git commit -m "repl: one more typo fix and so on..."

What’s next? Run tests to make sure everything is working.

Running tests locally

We have a script in Makefile for this as well:

~/node: make test

You can specify number of cores for running the tests. To do this, add -j flag.

~/node: make -j8 test

It will run series of checks, including the linter checks, tests. If everything is passed without any errors, you are free to go with a pull request. Otherwise, continue with fixing and figuring out why tests are broken.

Creating a pull request

Push your branch with changes to origin repository:

~/node: git push origin fix/1234

Go to NodeJS repository in Pull Requests tab and press the “New Pull Request” button. In the head fork specify your fork and in compare specify the branch that you’ve just pushed. Review the changes and create the pull request.

All you can do now is wait for feedback from the team. New commits can be pushed only in the same branch that you’ve pushed to origin. After some time, the team says you “LGTM”, which means “Looks Good To Me”. That is time you need to squash commits.

Squash the commits

You can google many ways to squash the commits into one, but I’m doing it with the reset.

~/node: git reset --soft master # Soft reset to master branch
~/node: git add . # Add all changes
~/node: git commit # Make a commit with a description of the fix
~/node: git push --force origin fix/1234 # Force push to update

That way you’re getting one commit that you can push with the force flag, so the NodeJS team can easily merge it into the master branch with clean history.

Stay up to date

From time to time you need to get the latest changes in master branch from other team. To do this, you can use fetch and rebase commands.

I’m doing the following series of commands (some of them I’m doing just in case, you know):

~/node: git checkout master
~/node: git fetch upstream # take changes from other teams
~/node: git pull origin master # In case I've made changes elsewhere
~/node: git rebase upstream/master
~/node: git push origin master # In case I'll made changes elsewhere

That way you can be sure that master branch is always up to date with the original repository.

Summary

I think, that’s it. You can leave your thoughts and responses here and I’ll update this article.

The main point of this article is simple — don’t be afraid to contribute into the projects you like. That’s not as scary as you think, anyway, that’s how I felt in the beginning.

Eugene Obrezkov, Developer Advocate at Onix-Systems, Kirovohrad, Ukraine.