Skip to main content

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.

Comments

Popular posts from this blog

Project: Boost-free Goblins, Part 2

Last time at the goblin_camp The mad developers went on a warpath to rinse away Boost from the goblins. Loud yelling and crying was involved, 52 of them. But now that all the yelling is out of the way, how should we do this? Repetition, repetition, ... I am personally a very lazy programmer. If I can make computer do the job for me, I would have the computer do the job for me. While hunting down every instance of a library manually is doable in small number, as it was for cstdint, Other Boost libraries are more widely used and require much more effort scanning the text.
Text.
Text.
Well, if we are talking about text-manipulation in sh ... Scripting my problem away My beloved hobby tools If it is not apparently already, I love automating tasks, and UNIX shell scripting had been my go-to solution for any binary scripting needs, especially in the days before I learned to program. This problem can be solved quite easily using few lines of scripts. Caveat We will be making a simple scr…

Act 1 Scene 1 Exeunt

Act 1 Scene 1 This year, I was able to dabble in open-source for the first time. It was a dream-come-true: a dream I long thought impossible to attain for my lack of understanding in programming language. How far have I changed since: not only is some of my code part of a program used by others, I am also hosting and developing a program as a part of the open-source community. Small, but a community.
This all started thanks to DPS909 class. Act 1 Scene 2 The Act is still on. I am just getting warmed up. What will scene 2 have for me in store? Only time will tell. For now, I am going to enjoy cultivating a community while also belonging to many others, finding my way through, contributing as I am able. Perhaps that will be my scene 2. It will be beautifully ugly, and I will love every moment of it. To my audience, even if imaginary If you are reading this and thinking there is nothing you can do to make a meaningful contribution to a program that you love, I am glad to say y…

The Hectoberfest

Hactoberfest A Hactoberfest takes place in October where coders are encourages to churn out a set amount of Pull Requests in the month. And a Pull Request is essentially a contribution made to the community. It is an interesting opportunity set to help motivate coders to take an active part in the open source communities in general. I certainly enjoyed the chance. This blog is dedicated to the Hactoberfest and acts as my index to my contributions and associated blogs. That Index I was talking about...A failed attempt that will be revisited and its blogRocketfuel and Zinc and its blogProtein Powder Realism and its blogA lesson on .308 and its blogA tribute to Hannibal and its blogAwl-pike with a weight issue and its blogThe Good I have made five pull requests, contributing to open source programs for the first time. In many ways, this is my dream come true; just 3 years ago, I never even thought this to be something within my power to do. I was always a consumer. Now, I have [con…