Make an OSS Contribution, Part 1: Pairing with Matt Swanson on Jekyll

Jekyll Bug Fix with Matt Series Index

Part 1 Table of Contents

This is the second of a short series on pairing with a super-experienced software developer to fix an open-source issue in Jekyll

Want to get updates on these posts as they come out?

How to read this guide #

Remember, a recurring theme of these videos is to highlight as much tacit knowledge as possible.

To that end, I’ve got a highly-annotated video walk-through below. Immediately after the video, I’ve got a list of time-stamps, showing in some detail what we cover in the video.

Next, I expand on some of what we cover in the video. I’m not sure what the best order is for reading/watching the video. Maybe skim the rest of this post, then watch the video, and if needed come back and read more of what I’ve written.

This first video covers just how Matt found this issue to work on. The constraints I’d given for what to work on were:

Ruby-related. I had suggested a few projects, Jekyll was one of them.
A small enough fix that we could get plausibly get a pull request up in less than two hours

Video Timestamps #

0:00 People misrepresent how easy it is to work on open source software
0:22 Why it’s overwhelming to jump into a project like Jekyll and just look for an issue to help with
2:19 exploring issues by Label
2:45 “good first issue”, “first time only”, “help wanted”, “up for grab” labels
4:23 Overview of this issue we’re working on
5:08 Matt Explaining/exploring this Tamil vowel mark issue, expanding upon his thought process
6:09 We’re mega impressed with the detail of this bug report
6:49 Following the issue link to StackOverflow to gain even better context for this issue
7:05 Matt explains that he doesn’t know a ton about Unicode, but that doesn’t stop us from working on this issue. (phew)
7:52 Figuring out how @DeepestBlue came up with his recommended Regex from the StackOverflow answer
8:25 Taking some guesses at what is going on in the given Regex
8:57 content with the issue, Matt now walks us through the rest of the thread, and his thoughts on how to best collaborate with the Jekyll maintainers
11:57 Matt and I enter the picture, as Matt leaves a comment claiming the issue

How Matt found this particular Jekyll issue #

This video opens with Matt saying:

People say, if you’re looking to practice

Oh, contribute to open source

and I think there is misrepresentation there of how easy that is to just… do.

Is it going to take five minutes, five hours, five days, five weeks?

And we spend the rest of this short (10 minute) video learning from Matt how he found such a well-suited issue for us to work on.

I was particularly impressed with Matt because he was so good at verbalizing his thought process. So, jump in as he walks us through how he found this issue:

He walks through examining the tags as an entry point, and how he “discards” most of the tags for further digging.
Once he’s looking at this particular issue, what is Matt looking for, and what is he ignoring?

What Matt noticed when looking through this particular Jekyll issue #

Timestamp: 4:23

The user reported a bug, and gave a very detailed explanation of the bug.

Lesson: The more detail you can give when raising an issue, the better

When Matt said:

This is way more detail than I would expect

My radar went off. We’re about to learn something very helpful, for opening/filing bug reports.

This bug report is so good that Matt and I were able to fix the issue in two hours. If it were a lower-quality bug report, we would have never touched this issue.

We both agree that neither of us know much about Unicode character encoding. But we don’t need to have extensive knowledge about Unicode to fix this bug.

Matt had to dig a bit to cross-reference detailed notes from the github issue and the linked StackOverflow question/answer. This is par for the course.

Matt:

I didn’t look up what this regex does…

He has some guesses about portions of the Regular Expression, but he still doesn’t need to know it in detail.

Also, 👏👏👏 for Ambarish Sridharanarayanan, @deepestblue, for opening this bug report. He not only opened the Jekyll issue, but he asked the StackOverflow question Why do some Unicode combining markers (like \u0BCD) not match [:alpha:] in Ruby? which led to the solution.

Had he just opened the bug report, and not asked the StackOverflow question and then interpreted between the answers there and the solution posed in the Jekyll issue, Matt and I would have had nothing to work with.

So, Ambarish has truly done 90-95% of the work for resolving this issue. Next time you report a bug, ask yourself:

What would Ambarish do?

Checks for Understanding #

I desperately desire for these videos to be of enormous value. That said, passively watching videos is a miserable way of learning things.

How do I, the creator of this video, justify that this is time well spent?

Here’s the general questions you should be able to answer after watching this video; they’re all generalizable to becoming a better software developer:

Why is “make open-source contributions” difficult advice to implement?
If someone suggested looking through open issues on the Jekyll project, what filters/tags would you end up using to find a good place to start? (hint - look at the issues, then all three pages of labels)
Go ahead and open up the issue we worked on. Find the specific StackOverflow answer that the issue reporter referenced, and find the exact instance of the RegEx the user suggested.
What are a few concerns about jumping in and trying to fix an issue someone else reported? Maybe not concerns, but topics to be aware of?
What are a few related issues that are not worth worrying about right now? (hint: configuration options, exact regex syntax, etc)

Next, head to part 2!

But before you go, why not subscribe to get updates when more guides in this series are done, as well as when future guides go up?