Github, Issues, Pull Requests

My Issues with Github and Pulling my hair for it

It all started when the venerable node.js implemented promise-based fs module. Shortly after, someone made Filer compatible with the promise-based operation. This is good. except now we need testers to ensure it works as expected. As an exercise in learning how to create issue and pull request on github, we were tasked to jump in and contribute. I chose to create a suit of tests for

fs.promises.read()

First strand of hair: the Beginning

As this was my first time working in a serious project, I wasn't sure how things are organized in this repository, and I wasn't sure how to check if certain tests were implemented or not. I started my adventure in the node.js fs module that shows test coverage, and while it was an eye-opening information, it was unfortunately less relevant to the tasks at hand. So I went back and started opening up the test files in /tests/spec/ instead. I found many tests for the traditional call-back functions, but not all that much for the promises. Oooh read looks interesting enough; let's do that one. First strand of hair fell off.

Second strand of hair: My Issue

Now it is time to revisit the repository in the github and open up the issue. This was fairly simple. Just create a post under issues, provide concise description, and if you want to take on the job, request that you would want to do so. Then the moderator would come around and assign the issue to you. Now it falls on you to deal with it. It fell on me to deal with read promise tests for Filer.

Third strand of hair: My own Batcave

Now things gets more interesting for someone new to git and github. So far, we were just browsing codes and making posts. Now we have to do some github magic to prepare our work environment before we even start making any changes.

1. We have to make a fork of the repository so that we can manipulate the code base to anyway we see fit. Simple enough: from the Web UI, simply click on the `fork` and follow the instructions.
2. We must clone our forked repository into our local development environment. There are couple ways to do this, but I am most familiar with the console environment, so I typed in

   git clone url-to-my-forked-rep forked_filer

3. You should also link the local repository to the original project as an upstream: for that, I put in

   git remote add upstream url-to-original

4. Lastly, create a branch to address the issue that as being addressed:

   git checkout -b issue-issue#

Now we are ready to code.

Fourth strand of hair: Fixing

I could have gone through the fs code in node.js and come up with all the possible tests I should perform. I am sure that would have been an interesting activity, and you are more than welcome to do so. That probably would have been thorough. For my test, however, I had decided to trust that the original tests for callback version is complete and decided to reuse the same logic but in promise context. There are few differences that I had to appreciate, however:

• When passing a callback function to the it(), instead of passing done into the function and executing it to indicate the termination of the test, I could simply not pass anything to the argument, return the promise object, and not call done(). The it() understands promise object and takes care of the test.
• When using callback function, the coder had to worry about the unexpected routes and implement necessary tests to ensure those routes are also anticipated. In the promise-based test, if I expect resolve() to happen, I only have to worry about .then() and not bother with .catch(). If it ends in the latter, the it() will take the returned promise object and fail the test as expected. This makes coding a lot easier as I only have to worry about the success conditions and not worry about the alternative possibilities.

Each time a test is implemented, or a significant code has been done, make sure to perform

git commit -am'my-commit-message-here'

. This is the beauty of git that we will all learn to appreciate if we are not already in love with it.

Fifth strand of hair: The Pull (Request)

Now that the tests are implemented, and bunch of stuff are committed, we need to go and make a contribution. Go to the original repository and make a pull request. Within it, indicate that the source of the code is from a different repository, and have the pull come from your branch in the forked repository. Leave a small message and commit.

No more hair

The rest is more like having a conversation with all interested folks. They suggests stuff to you, you try to understand where they are coming from, and perhaps even implement those changes. We learn from these experience, or perhaps teach others by justifying your choice of action. At some point, once the conversation reaches its end, the code will get merged. Well, I have yet to get there, so we'll see how that works out.