Getting Your Foot in the Door for Open Source
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:
- The documentation was outdated and permission functions were in the project
- 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.
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 add to add the updated README file to the staging area
and commited the file with an accompanying message using
git commit -m
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.
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.