Getting Familiar with Open Source (OSD600 0.1 Release)

Introduction

As part of the Topics in Open Source Development course I am taking, we must make contributions to real open source projects. We are free to choose what kind of projects we would like to work on, and the type of contributions we would like to make. The first release however, is involves contributing to node package called filer as a chance to get our feet wet with git, github, and open source development in general. This is the journey I took in my small contribution to filer.

A rough outline of the process I took:

  1. Filing an Issue
  2. Setting up a Local Repository
  3. Running Existing Tests Locally
  4. Working on the Issue
  5. Making a Pull Request
  6. Responding to feedback
  7. Getting involved in the Community
  8. Reflecting on the Process

 

Some Background

Filer is a package available in node for a file system that mimics the built-in file system fs in nodejs. However,  fs only functions in a command-line environment, but does not work when run in a browser. Filer is intended to run on both.

 

Filing an Issue

The first thing to do was to pick an issue to file. Namely, something worth adding to or changing in the project. I opted to make some unit tests for fs.appendFile() since my Lab1 post involved analyzing how the method works. After surveying the existing tests, and the related issues already filed, I noticed that none of the tests involved manually setting file system flags such as ‘r’ (read), ‘w’ (write), ‘a’ (append). Perhaps this is because there probably isn’t really any reason to ever use a flag other the default. Nevertheless, it is worth checking that the actual implementation matches the documentation.

I filed Issue #463, requested permission to work on the change and got to work.

 

Setting up a Local Repository

I’ve had a github account for over a year, and yet my only repositories were the Hello World repository and a newly created repository for my Capstone Project. I had always been meaning to get more comfortable using both git and github, but without a project to work on it always got postponed. Fortunately, I now have a a good reason to use and master it.

I learned that I should fork a repository first, then clone my own fork. After fiddling with git commands a bit, I had a local version of filer. After stumbling a bit, I realized that even getting everything up and running is a bit of a min-challenge itself. I had to make sure all the packages were installed, since they don’t come automatically (npm install) and learn how to run the tests (npm run test).

 

Running Existing Tests Locally

This lead to the first big hurdle. Because of the difference in line endings between unix and windows machines, I kept getting the following errors on every single test being run (1000+):

Expected linebreaks to be 'LF' but found 'CRLF'

However, I had set up git properly for line endings (as far as I knew), and done the same with Visual Studio Code as well. After a lot of troubleshooting (including reading links posted in the slack by people with similar problems), I got… nowhere. Eventually I gave up for the night. A restart of my computer seemed to have solved the problem. My guess is that one of the many things I did in troubleshooting ended up kicking in after the restart. I’m still not happy with my understanding of how line endings work, but at least I am a little less scared by it now. At some point I believe I installed everything to my desktop as well, and was met with the same problems, but in the end I was able to get everything running on my laptop for school as intended.

Then came more issues. The test command ended up slowly going through tests and stopping around 80 (out of over 1000). After some more fiddling, it ended up going up to around 380, but still stopped after that. Taking some cues from “CHROME HEADLESS” that I kept seeing when I ran the tests, I installed Google Chrome. That seemed to help.

Overall, getting everything to work was surprisingly difficult. Furthermore, considering my goal was to create a simple test, the fact that getting the existing package to run took so long was somewhat frustrating. Hopefully as I gain more experience with git, and whatever environment I am using, this step will take less time in the future.

 

Working on the issue

Finally able to begin, I took a look at the other tests available for appendFile() and found a test that was mostly similar to what I needed (it passed { encoding:’utf8′ } as the option parameter instead of { flag : ‘a’ } (for append). But the output should have been the same, since both the ‘utf8’ encoding and ‘a’ flag are default parameters for appendFile. There was very little to change. And yet…

The test failed. How? The theory behind my test was very simple, very straightforward, and very hard to get wrong. I searched high and low to make sense of the error code involving a mysterious copy_t method that caused it to break. Not much luck on that front. I spent a lot of time trying to find what was wrong with my test.

In the end, I don’t think it was wrong. When I took a look through the implementation of appendFile(), I found that the validation of options worked differently for the flag compared to the encoding. It seemed that if no flag was passed, it was taken care of by the following line:

flag = options.flag || 'a';

That meant that for a partially formed options object, you didn’t need to include the flag attribute. But the same wasn’t true for the encoding attribute. This was proven when {flag: ‘a’} caused the operation to fail, while { encoding: ‘utf8’, flag: ‘a’ } did not.

I decided to submit two tests instead of one, to demonstrate this difference (and prove that the bug exists and was what I claimed it to be).

First Pull Request

I took my findings, gathered my tests, and submittied Pull Request #494, unsure if a test that failed could be accepted into the project. Although I was confident that I had actually found a bug in the implementation of appendFile(), the concept was new to me. Would I have to fix the bug before the test got accepted? Would I continue working on filer for the second release, or change to something else? Would anyone end up finding a flaw in my argument? Only time will tell.

 

Peer Feedback

So far, none of the comments on my pull request have invalidated my work or pointed to any revision. I believe this may take more time.

 

Getting Involved in the Community

I reviewed the pull request of two other students. The first was a straightforward test with no errors. The only suggestions I made were with regards to whitespace and grammar.

The second was a bit more complicated. The test did not pass, though I was not 100% sure about why. The intended goal of what was being tested was unclear , though I did find something to be improved nonetheless.

In both cases, the pull requests did not overlap with other issues or existing files.

 

Conclusion

I enjoyed getting involved with open source projects. I’ve waited a long time to get involved with real projects, and I’m glad to have done it. It a good way to learn, and the community is friendly. I’m excited to continue with it in this course, and hopefully beyond.

As far as the work itself, I found that it is hard to predict how long something will take, and where the trouble will come from. Hopefully by planning ahead and managing my schedule I can stay ahead of the problems.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s