First Pull Request to an Open Source Project

This post is a continuation from my previous post on the google phone number library web service project. I want to begin by stating that while I thought contributing to another person’s repo of the same project would be easy as I’ve done a bulk of the work myself, this was not the case.

The Difficulties

The biggest issue was trying to debug why unit testing wasn’t working. Initially, I thought it was the unit testing framework because I could use Postman, a HTTP client application to test the web service, to create desirable results. However, every time I ran the unit test, I would get an error that says

res.json is not a function

This didn’t make sense. To elaborate on the issue, “res” is the variable for the HTTP response received by mocha after sending a file containing phone numbers to the web service for parsing. I tried the following:

1. Console.log(res) to see if the variable contains data and it does!

2. Using VSCode’s debugger to step through the test code execution as suggested by Sean Prashad.

The problem I’ve encountered shortly was that the code would jump into Express JS’s library. I began hopping through code that I didn’t understand and I did not manage to come out of it within a reasonable amount of mouse clicks.

The solution

I thought, if I could start the server just fine, then I should trace the steps in the code and compare it to my test code setup to see what was different to get insight into what was wrong.

As it turns out, the test script had incorrectly required the route file instead of the web service app itself. It immediately became clear why it wasn’t working. Mocha was not using the web service app for testing, but a route of the service app.


In total, I’ve a few contributions to the repository.

• Fixed unit tests to ensure they all work
• Added the ability for the web service to decode Base64 formatted text files
• Added the ability for the web service to handle invalid GET requests (i.e. if the user provides no phone numbers to /api/phonenumbers/parse/text/ , the web service returns an empty array as expected)
• Added tests for new functionality as listed above
• Added Travis CI support for the repo

What I learned

During the entire process, I had to research a number of things. The first thing was Base64 conversion. Up to this point, I had no idea that files uploaded to servers should be Base64 encoded. In addition, I do not know how to encode or decode the text itself. Luckily, JavaScript already provides that functionality.

Troubleshooting process

The second thing I learned about was the troubleshooting process. After this incident, I realized the way to debug faster is to trace the code backwards, from the point of failure and to consider all dependencies that the code depends on. While my methods may change in the future as I gain more experience, this is all I know thus far to be best practice.

Debugging with Mocha

Third, it was interesting to learn about debugging using the VSCode editor. If you’ve used Visual Studio in the past, you will feel very at home with VSCode. Keyboard bindings such as F5 to start with debugging and Ctrl + F5 to start without debugging were all the same. The gutter areas between the line number and the edge of the editor are still the areas you work click to mark break points to name a few. There are lots more similarities. Here’s what I did to configure and start my debug session with mocha:

1. File > Open

2. Find and select the folder for your application

3. Click on the debug icon Screen Shot 2018-02-11 at 12.53.17 AM on the left menu bar, then select the settings button Screen Shot 2018-02-11 at 12.53.44 AMnext to the play button.

4. With your mouse, click inside the array of “configurations” property and click “Add configuration” button.

5. Select “Node.js Mocha test”

Screen Shot 2018-02-11 at 12.57.38 AM

6. Navigate to the part of my code where the issue is happening and set a break point by clicking on the gutter area of the editor between the left edge and the line numbers. A red dot should appear.

Screen Shot 2018-02-11 at 1.04.16 AM

7. Click on the play button to begin debugging with mocha.

Screen Shot 2018-02-11 at 1.05.22 AM

The debugger will then pause at those breakpoints and you will be able to expand the “variables”, “watch”, and “call stack” of your code at any given point on the left panel.

Travis CI

The last thing I’ve learned is how to use Travis CI and how amazing this new tool really is (once you understand how to set it up). While I thought it would be super challenging, it did not take as long as I had anticipated. The fact that this tool can automatically clone your repository, install the environment and dependencies based on your .travis.yml file, build your code and even run tests every time a push or pull request (or both) is done will make working projects in teams or alone much easier. It allows higher quality applications to the built by testing and building the latest version of the code frequently rather than waiting for one major release to be committed by a single developer all at once and testing after, which then results in long debugging and merging sessions.

I’m glad I’ve done this assignment. I feel much more prepared. The fact that I had to step through the process of forking a repository, creating a branch to work on a fix, then add, commit, and push those updates, and finally create a pull request has made me much more comfortable at contributing to open source software.

I look forward to contributing to a major project soon. In fact, Microsoft VSCode is on the list next!

Until next time.

Leave a Reply

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

You are commenting using your 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