My First Contribution to Open Source
I read Linus Torvalds’ book, Just For Fun, and I caught the open source bug. I admit that this is probably a poor choice of words, but let me continue: He described open source as a way to simply “let everyone play.” Some people describe open source in idealistic terms — others simply capitalize on it. But the way he described it in his book, Linus Torvalds seemed to simply see it as a good system and a way to let lots of people have fun.
A little weird to think that this is the same guy who wrote that “whoever was the genius who thought it was a good idea to read things ONE F*CKING BYTE AT A TIME with system calls for each byte should be retroactively aborted” (source), but lots of his quotes are taken out of context and lots of people respect his no-BS attitude.
You can find a million articles online about why you should contribute to open source, including one with the click baity title “Why you should think twice about contributing to open source.” Though the title is misleading, there are reasons you might want to think twice about contributing to open source…namely that doing so could violate company policy. My company’s previous policy was to completely forbid us from contributing to open source, period, but more recently it gave us permission to fill out requests.
There’s a project I’ve wanted to contribute to that’s hosted at a UC college: It’s a widely-used hardware simulation software, which is complex and hard, but it also has an open source website set up fairly recently. Hamedy describes some pretty impressive contributions he made, but said that he started by fixing hyperlinks. That’s it. His first ever open source contribution was fixing broken links. I could totally do that and then brag about it later!
I looked through the open JIRA issues on their website, and that’s when I found it: The lowest-hanging fruit of the lowest-hanging fruit:
A README change! That was it! There was an issue open for more than two months about some README change no one wanted to do.
I know what you’re thinking, though…that wouldn’t be very meaningful. So I found out their “previous” and “next” buttons across the entire website simply linked back to the same pages…I discovered it myself, but it had also been in their JIRA for months. Based on the comments, it looked non-trivial. If I finished the first change easily and at least got a feel for their workflow, maybe I could try to fix the previous and next buttons. These issues were both fairly old…I had a feeling this team’s website was not their top priority. Maybe if I fixed these, I could one day build enough of a reputation to be trusted with issues in their core infrastructure.
So there it was. I knew what I wanted to do. I submitted a request with my company to contribute to this project, and waited. I answered some questions in an email. I wanted more. In the meantime, I tried to get this team’s attention by fixing some grammatical errors on one of their Google Docs. They accepted the changes. I felt good for about five seconds.
One Month Later
There were a few conditions, like “don’t commit proprietary code to open source” and “don’t advertise the open source project at work,” but nothing that unreasonable.
My manager jokingly asked me if the project still existed. Yeah, not only did the project still exist but the issues were still open.
Their website was set up with Jekyll. I personally thought that the only two possible ways to make a website were with Vue.js and SquareSpace, but Jekyll actually had a community behind it and a lot of respect for its efficiency and simplicity. Jekyll used Ruby, which I knew nothing about. The website had lots of files in markdown and standard HTML, which I did know things about.
Getting Ruby and the dependencies installed on my main computer was surprisingly difficult; it took around 30 minutes to set up on my older computer that ran Ubuntu, but the newer computer was way faster. The easiest part, of course, was making the markdown change.
Done. Accepted. Merged. I felt pretty good for about five seconds.
The Less Trivial Contribution
That was Sunday. I had some free time to look at the next thing.
Okay, so…there was this directory with all these HTML files. For some insane reason they all had the same spelling error, but the buttons very clearly linked to nothing. So of course this didn’t work. I went to a button, added a link to the next page, and it worked! Wow. Amazing. I would just do that for every page.
Oh, wait a minute. That entire directory was auto-generated and got overwritten every time. Made sense.
Now clearly this “Nadia” person knew something about Jekyll, I reasoned, yet she still wrote that cryptic description about “next” and “previous” skipping around in spite of her fix. Rather than research further, I decided to go into google and type “jeckyll next and previous buttons.” I went to the first page. I found out exactly what page to target and copied this resource’s code into the part for “previous” and “next” buttons. I hit the next button and held my breath. It worked! Amazing! I had managed to do in less than two hours what members of this team had clearly not been able to figure out in months, possibly because they were too busy but more likely because they never thought to use Google.
I posted on their JIRA and went to bed feeling really, really good.
I woke up. One of their engineers responded!
To be clear, this main website guy was a PhD candidate with almost a dozen publications. His main partner on the website was an assistant professor, computer architecture researcher, and PhD holder (I think their formal title is “PhD holders”) who basically headed the entire project. They were also two major people behind the core infrastructure, the actual simulator. I wanted to impress them or at least get their attention.
He responded! Yes! I felt so good. I had already made a short commit and decided to give it a last check. I hit the “next” button. It worked. I hit it again. Oh no…
For no reason at all, it jumped right from “building” to “cache config.” Then it went to “example configs.” What was this? The “next” and “previous” buttons were not working in order at all. I decided to reread Nadia’s comment.
I was devastated. I decided to apologize for wasting everyone’s time, left a comment I hoped they would forgive me for, and then take a walk of shame around my apartment as I contemplated how I could have been so stupid.
I was getting ready to remote into actual work. I decided to give this another look. “Building.” “Cache config.” “Example configs.” Wait a minute, that wasn’t arbitrary. That was alphabetical. What do you do when you want to force a bunch of files to do as you wish in alphabetical order?
I prepended a bunch of numbers. I don’t know if I’d win the MacArthur Fellowship for a solution like that, but it seemed to work. 8…9…ah, there was an issue with 10. Fortunately we were outside of code/HTML territory in the wonderful land of libraries, so someone let me know I could prepend 0. Fine.
Yeah, worked for me. No use feeling happiness or excitement again, but I made another commit.
Excellent. They had a code review ready for me within a few hours. That night I looked at it again.
Was that Actually a Smart Change?
My reasoning was that Jekyll automatically named markdowns by prepending timestamps, so that alphabetizing them made them appear in date order. But this site was migrated, not originally made in Jekyll, and prepending numbers was the best fix. That would have been excellent reasoning, had it actually been true. Unfortunately, it was not.
In hindsight, that change was not the best…but it was something other people thought of. This guy was so annoyed by it, in fact, that he offered a $100 bounty to fix the issue.
I would be curious to know who collected the bounty, if anyone, because apparently there was a much cleaner way to fix it.
Searching Stackoverflow today takes you to this, but the change was already merged by the time I had seen that. It was not the most elegant solution, but it did work and I didn’t think there was anything insane about it.
The Dead Page
Their PR pointed out that a single page wasn’t working correctly, but I realized it was actually missing entirely from their navigation menu because the markdown had been mislabeled. I pointed this out that night because I was hoping to fix a bug with the left menu collapsing.
What is Gerrit and why is it a thing
Those two worked a very quick PR and merged it themselves. I wanted to work off of that change.
So I did. I pulled master, worked off of that, then attempted to push. Gerrit complained there was no ID under the merge. So I did a git rebase. Then it complained it had already seen the commit from their PR. What was this? Clearly I did not understand the workflow.
People really liked Gerrit. There must have been a good reason. But I could not, for the life of me, figure this out. How did you sync the latest changes? Apparently users were supposed to amend their commits, instead of making new ones during code reviews?
Probably when you got it right, Gerrit wasan amazing tool with simply one commit message per every feature, including the code review changes because you simply amended. But…ugh…I didn’t get it. The workflow was to fetch, but…I didn’t even want to get into the issues I was having. Github worked fine enough for me.
So I just complained.
The next afternoon, they simply did the merge for me and responded to my comment.
They worked a fix on top of mine and got the merge ready. All I had to do was approve.
And yeah, that was it!
15 minutes later, I saw my name go up to their github mirror as a very minor contributor (everyone is minor compared to those two. They wrote like 95% of the code base). Then I saw it go live! The next and previous buttons worked!
Closing Thoughts
There are a bunch of interesting angles to take when thinking about open source. It’s worth a lot of money. It makes things free. It could be the reason why, if you want to build a website, you can simply download Bootstrap or Vue.js online and maybe even report/fix bugs on it instead of opening a shopping cart and pulling out your credit card. If we went back in time and undid open source, we might have found a vastly different landscape.
But is open source all goodwill and community-building? I mean, companies also recognize that it’s a useful way to get free testing, and enough light to make the bugs run away.
But here’s the thing: It’s the closest thing you can get, without leaving a job or starting your own side business, to actually seeing how another software team behaves. You get to see what their workflow is, what tools they use, how they deal with people. It’s almost like a very small taste of bypassing an interview entirely and just jumping straight to the work, then walking away as soon as the latest feature is done.
I liked it. It was interesting.
