Getting Your Foot in the Door for Open Source

Open source development can be intimidating considering it can involves working on well established code with thousands of lines of code that thousands of other developers have worked on. Often times it can be hard to find where to start or how to contribute something meaningful without digging through the entire code base. This blog post records my first contribution to the filer project, a POSIX-like file system interface for node.js and browser-based JavaScript.

A meaningful contribution doesn’t have to be something big, as a matter of fact it can be a simple change that takes less then 5 minutes. Depending on the size and scope of the project you’re working on I find that it’s a good idea to comb through the documentation to learn the functionality of the code. The documentation is a great place to find opportunities for an initial contribution to any open source project. A project can have the most amazing features but they won’t help anyone if no one knows how to use it. As such documentation updates can have a huge impact on the project as a whole.

During my initial read through of filer’s documentation I noticed that the “Getting Started” section noted that permissions related functions were not implemented in filer.

However as I kept reading the documentation I noticed there were examples of permissions related functions.

So this could mean one of two things:

  1. The documentation was outdated and permission functions were in the project
  2. The documentation had functions that were in the pipeline but have not been implemented yet

So to figure out which one of these was the case I did a simple repository search.

And it seems like the code for permissions functions was in the code already so the “Getting Started” section of the Readme was just outdated.

Since that is the case let’s create a new issue on Github by navigating to the issues tab and clicking the new issues button.

The issue I created can be found for the documentation update can be found here.


Making Changes

When working with projects hosted on Github always start by forking the project by clicking the Fork button.

This will create a clone of the repository on your account. This will be your version of the code and where you will add all your changes. Then clone your repository on your computer by copying the link that’s shown when you click the “Clone or download” button

and use the git clone command in the Terminal if you’re using Linux or OSX. If you are using Windows look into Git for Windows.

So the resulting command for me was git clone https://github.com/jrkong/filer.git

This will download a copy of your repository to your working directory. Navigate into the directory and create a new branch using git checkout -b and name your new branch whatever you want but it’s usually best to name your branch after your issue.

For me, I ran git checkout -b issue-487

git checkout changes the branch you are working on to the branch you check out and the -b option creates the branch before changing your working branch to the new branch.

Now let’s work on the change. I use Visual Studio Code as my text editor.

The README is a markdown file and VS Code has a nifty preview function that lets me verify my changes.

After saving my changes I go back to my console and verify that git noticed my changes with git status

I run git add to add the updated README file to the staging area

and commited the file with an accompanying message using git commit -m

I use git push origin HEAD to push my changes to Github.

From there I create a Pull Request on Github to have others review my code and merge my changes into the main codebase.


Reviewing Code

Contributors can review other people’s code by looking at the project’s pull requests on the Pull Requests tab.

Two pull requests stuck out for me:

Where both pull requests include changes to the file package-lock.json which was odd as those changes seemed unrelated to the bug. I commented on both PRs and asked for those changes to be removed from the PR.

For those unaware, package-lock.json is a file generated by node and it essentially acts as a manifest for the dependencies installed by npm install so subsequent installs can use that dependency structure. Changes in package-lock.json can appear when one of the installed dependencies differ (perhaps in version) then the one recorded on the Github package-lock.json. This could be useful for troubleshooting issues that occur due to an update from a dependency. However, as the dependencies installed by npm can have an acceptable version range the package-lock.json can change. This accounts for the changes in package-lock.json. Depending on who you ask this can be counter intuitive and there are a number of ongoing discussions about it’s usefulness which I don’t plan to go into. However this does seem to be a trap that new Node contributors tend to fall into so believe it’s something to keep in mind.