Collaborating with others in open-source

Introduction

This week I had a chance to work with Leyang Yu, a fellow student from my open-source course. Our task is to review each other's implementation of the static site generator and file any issues we find on GitHub.

For a socially awkward person and introverted person like me, the thought of having to take a look at someone else code was horrifying. Will I be able to examine the code as thoroughly as I can? How should my wordings be when filling the issue? Should I make any recommendations? These were all the questions and pressure that I put onto myself before trying it out.

And, to my surprise, the experience was actually pretty enjoyable.

Getting in touch and first impressions

First, I reached out to my partner on Slack was excited to find out that Leyang was also a web developer like myself, and we both share an interest in JavaScript. Because of this, I was able to learn a lot just from watching my partner code alone. I was amazed to see how they insert HTML contents using only a simple template HTML file and a few replace() functions instead of using an npm package like I did.

In addition, the way Leyang organized the code made the experience of navigating through the code less challenging. It is something that I could learn from as I struggle many times trying to understand what I wrote.

Reviewing and debugging one's code

After cloning the project to my computer and ran it through a couple of tests, I was able to spot out some problems. The program had no trouble accepting files in a given directory and convert them into HTML. However, when generating links for the converted files, the behavior was not as expected.

Example:

Given a `folder` directory with the following files:
2efgt.bin  'a text file.txt'   abcd.txt   jkjkjk.js

Expected output:

<div>
    <ul> 
        <li><a href="./a text file.html">A text file</a></li>
        <li><a href="./abcd.html">Abcd</a></li>
    </ul>
</div>

Actual output:

<div>
    <ul> 
        <li><a href="./2efgt.html">2efgt</a></li>
        <li><a href="./a text file.html">A text file</a></li>
        <li><a href="./abcd.html">Abcd</a></li>
        <li><a href="./jkjkjk.html">Jkjkjk</a></li>
    </ul>
</div>

Leyang and I had a long discussion on how to solve this, with myself suggesting the use of a .filter() to sort out any non-text files. In the end, we decided to add an extra check for the files' extension in one of the if statements.

In addition, I also gave my partner some suggestions on the README.md, mainly to include an installation guide and some extra examples/demos for other developers.

As for my part, Leyang discovered that my program had trouble accepting input with spaces. I noticed that this behaviour was because of how yargs - a package I used to make my CLI - parse arguments. By default, arguments are separated by spaces. Thus, only the first word of the file/folder was registered, which resulted in an error saying the specified path doesn't exist.

Example:

~/[some-path]/a file.txt

will be registered as

~/[some-path]/a

After some time, I was finally able to figure it out by changing the input type and adding an extra step to process the user-provided input.

Another issue that I had was the content when calling -v was missing the program name. It was not difficult to fix as I only needed to change the function displaying the version to include both the name and the version number.

Conclusion

The experience of working on the code in a community was still pretty new to me, but it is something that I am willing to do again in the future. As the annual Hacktoberfest is getting closer, I cannot wait to meet up with new people and see which project I will be contributing to.

Cheers 🍻!

Photo by James Harrison on Unsplash