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.
Labels:

Comments

Post a Comment

Popular posts from this blog

Creating a patch for GNU GCC using Git

Overview and Target Audience The GNU GCC project followed a blend of a traditional method with contemporary git tools when it comes to contributing code, making the experience unique from some other, git-based projects. This blog post will explore different aspects of the process, helpful commands, and various scripts that would make the experience more pleasent for new contributors. While this blog aims to help new contributors get acustomed to the GNU GCC code culture and make contributing easier, it must be stressed that this is not in any way in-depth exploration of the process. This should help you put your first foot forward; the community will help you take the rest of the steps from that point on. This post also assumes the user is in a POSIX environment (e.g. Linux, FreeBSD). Git and GNU As stated in this phoronix post , GNU GCC made a full transition to git early 2020. As of this writing, the community seems to be adjusting to the new tools. GNU GCC hosts its own git serve...
Post a Comment
Read more

Debugging with GCC: GIMPLE

GCC and GIMPLE One of the very first thing GCC asks the GSoC applicants to do, even before writing the application, is to try various different debugging techniques using GCC. I was personally familiar with the basic, compile-with-g-flag-and-use-gdb method. Turns out, there's more: GIMPLE. A Simple but Non-trivial Program Problem Description The instruction asks to compile a simple but non-trivial program with some flags that generates debugging information: -O3 -S -fdump-tree-all -fdump-ipa-all -fdump-rtl-all . Because I was keep reading on ways to debug GCC just prior to the statement, I immediately thought "GCC" and tried make -j8 CXXFLAGS="-O3 -S -fdump-tree-all -fdump-ipa-all -fdump-rtl-all" . This was a mistake: turns out, GCC can't be compiled with those flags. Thankfully, GCC developers have a very active IRC channel for me to signal SOS. Resolution jakub and segher were quick to respond to my call for help. jakub: it isn't meant that y...
1 comment
Read more

Researching Awl Pike

Last time... In my previous commit, I had the pleasure of studying the guns and their ammo and how they are reflected in the world of Cataclysm-DDA. This time, the some members of the community were buzzing about a 3-meter-long pointy stick called awl pike. Awl Pike The awl pike is basically an extra-long spear designed specifically for use in a formation attack. A formation of 3+ ranks hold the longest possible stick at their disposal and poke the enemy that stands in front of them or charging at them. It is very powerful weapon against things that stands in front of them, but due to the need for formation and the shear unwieldiness of the weapon, it is not very versatile and adaptable to changing circumstances. In a one-on-one combat, the weapon would be very difficult to stay effective. How do I know all this? Well, there was the entire discussion about it in the issue page. Like I said, this kind of games brings out the geeks from their closets and provide the floor to sp...
Post a Comment
Read more