Exposure to Open-Source

I’m taking a great course on open-source development in school, and one of our first assignments was to make a contribution improving test coverage for the Filer web filesystem project. The assignment was designed to expose us to the common workflows and tools involved in contributing to open-source projects on GitHub, so I’ll share a little bit about my experience completing it and some of the challenges I ran into.

Decisions…

To start, I had to decide which method I wanted to improve test coverage for. Filer recently merged a Pull Request adding support for the new fsPromises API which did not include any tests, so I created an issue in the repository and set out to add tests for the fs.promises version of the utimes() function. I have never done tests in Javascript before, and wanted to choose a method that already had tests for the callback version of the function, so I could just modify them slightly to test the promise version. I figured this would be a more efficient way to learn how Mocha works, and then I can just focus on making the tests work with promises.

Getting started

Every project has its own way of storing files and resources, but most of the time tracking something down is pretty straight forward (especially with the convenience of a search bar). In this case, I had to find the test file for the utimes() function. I figured it would live under /tests, and some more digging and ctr+f-ing brought me to /tests/spec/fs.utimes.spec.js.

After finding the file and figuring out what I wanted to implement/add, I had to create a new issue detailing the bug/feature I wanted to work on.

Fork, Clone, Commit

In order to open a pull request on most projects, you need a forked version of the repository. I went ahead and forked Filer, cloned it to my local machine, and started making code changes.

Figuring out how to write the tests took a bit of time, but by looking at mocha code samples online, analyzing some of the other tests (callback and promise versions alike) in the repository, using the documentation and running some small local tests to figure out how things worked, I was able to write the tests for the fs.promises version of the function.

With significant changes ready to go, I saved the file, ran git add command to stage it for commit, ran git commit and git push to push my changes up to my forked version of the repository on GitHub.

At this point, if you can run and test your code without problems, it would be safe to open a pull request for review, which you can add further commits to in the future and use as a handy space to discuss and refer to your code changes. In many repositories opening a pull request will automatically trigger testing (in this case it was TravisCI), which must pass before your code will ever get merged. Because of this, it’s probably best to locally run and test the code (usually projects will have information on how to contribute which would include information on how to run the tests), so when you open the pull requests all their automatic tests will pass and they can conveniently review your code. Alternatively, if you can’t figure out why tests are failing, running the code and tests prior to opening a pull request allows you to at least try figuring it out so you can give them more information, or be more informed, when it’s time for them to review your code and discuss the problems.

Running and testing code with changes

This is the part where I (and probably most people) encounter problems.

When I finished making and pushing my changes, I tried running npm test, which runs lint followed by karma-chrome according to the Filer contribution documentation. The first run revealed a minor ; error caught by eslint which I immediately fixed. I ran it again, but this time there was an error about missing chromium-browser. I downloaded it so the /usr/bin/chromium-browser path (I forgot to screenshot the error, but I think it indicated that it was searching that path) existed. Running npm-test a third time hit the jackpot, and all tests passed with no errors or failures 🙌.

Making the pull request

My code was passing all the tests, so I was ready to open my pull request. I linked it to the original issue, and added some detail about what it fixed. I had some questions about the code for the tests I wrote, so I reviewed my own work which allowed me to link my comments to specific line(s) of code. No one has reviewed the code yet, but if further changes are required I can push additional commits to the branch and they’ll display in my open pull request.

Reviewing other peoples work

Besides for making contributions and discussing your own code with reviewers, it’s important to get used to reviewing and discussing other people’s work/code as well. That was the next part of this assignment, so I went about sifting through my peers pull requests and found one I felt I can comment on.

The challenge I had with this part is that many people implemented their tests in different ways. While I found some open pull requests that clearly had problems with the code, I felt my knowledge was too limited to be able to point out the exact problem(s) and make recommendations. Instead I found a pull request with tests implemented similarly to mine, and felt confident enough to drop a comment or two. The author actually modified their code based on my comment, so I guess it was somewhat helpful 🎉.

Closing remarks

I can already feel how exciting it is to be part of the open-source universe, and I haven’t even scratched the surface of the surface. I think the biggest challenge will be having to jump into projects where I’m unfamiliar or totally clueless about some of the tools or frameworks (or the code in general), but this challenge is also what I love most about doing software development. The process of looking at something and not having a clue was it does or how it works, to slowly tackling one question at a time until you have enough of an idea to really start exploring and learning it more in depth, until you can actually contribute something useful regardless of your expertise. This is the process of learning and growing, and I’m glad I get to be a part of it in a way that benefits other people too.

I’m glad I chose this course, and I’m excited to see what the future holds.