foo::bar

Blogs and RSS are cooler than ever

Hack a duck

Contributing to an open-source project like DuckDuckGo is a fun and fulfilling experience.

My first contribution to the search engine DuckDuckGo is now live. It’s a simple “instant answer”, like many others available. So if you want quick meaningful data regarding QoS and uptime, call the duck. It’s nothing revolutionary but it’s always pleasant to watch something you’ve worked on go live.

I was already a part-time user of DDG, a search engine that does not spy on you, when I ran into “DuckDuckHack - Now you can hack your search engine”. The idea is simple : “Hack on things that you know and care about to improve search results for your community”. There’s a large “Start coding” button, but you can also contribute without writing code by submitting and discussing ideas.

My criteria for an open-source project

Before I started, I had considered the following criteria:

Working on a great tool within a hostile or an unwelcoming community is not my cup of tea. The very nature of the activity, even if you implement a feature entirely on your own, is to work with other people. You will be in touch with another or several other human beings to discuss implementation, look and feel, usability and relevance.

I first connected to the DDG IRC channel. Somebody asked a question and he received a friendly answer. Good. Then I went to their GitHub repo and I randomly picked one or two pull requests. Healthy discussions we taking place, with mutual respect between the developper and the DDG staff and collaborators. Obviously a friendly community I thought; that part was covered.

Some projects are better managed than others. If you go to the bug tracker and see many issues remain unanswered, that’s not a good sign. If pull requests are piling up, I don’t feel like submitting mine. With DDG, pull requests were processed in a timely fashion and the idea site was active. A strong indication that your hard work will be taken into account.

From there, you can already jump in. I followed and commented some ideas, asked for a status update when appropriate. I noticed an idea for a goodie was open for a year. I tracked the corresponding pull request. The work was done, the PR was closed but the goodie was not live. Weird. I asked on IRC and… a committer apologised that it got lost, although I wasn’t even the author! The feature was quickly revived, the original author popped in to finalize the job and it was rolled to production. How friendly is that?

Ok, so from here, you know you have a nice community and a well-managed project. But as a contributor, I like it when I can jumpstart quickly thanks to up-to-date documentation and easy-to-configure tools. It’s obviously the case with the doc. They use GitHub and Codio, a web IDE where everything is already set up for you. No need to install any toolchain on your computer! That’s super cool.

Of course, you don’t expect all projects to be perfectly clean and tidy. I suppose LibreOffice and Mozilla Firefox require a little more than a git pull followed by a grunt serve to run. I just expect the project to be reasonably well documented and with a decent toolchain, given its size. No doubt it was the case here.

There’s always an overhead for your first contribution however, no matter what. It’s just nicer when this overhead is kept as low as possible. Split your overhead costs by contributing more than once ;-)

And finally, it’s better to work on something that matters to you, for instance a program or a tool you use on a daily basis. One might also argue that open-source contribution is always good for karma anyway.

Hacking the duck

Required skills:

I think that covers all you need!

First, find a validated idea to work on, or submit your own and wait for feedback. I spotted the uptime calculator and it felt like a good match for a newcomer. Make it clear that you are working on it (more on that later). Then Determine your instant answer type amongst SPICE, GOODIE, FATHEAD and LONGTAIL then navigate to the corresponding section of the documentation.

Fork the repository and start your Codio box as explained. I strongly advise you take some time perusing the code of existing “goodies”. It is good practice to create a branch on your forked version of the repository, although in this case, working on the master branch should cause you no harm. If you are not familiar with git and GitHub, you might want to brush up your skills in that area first in order to be comfortable when the time comes to submit your work.

For me there was a catch: it’s all in Perl, of all things. Yep. Well, the language should not be a concern for a seasoned developer (unless it’s VB), so I thought I could live with it :-) I was a noob at work. This was a good occasion to discover Perl. It’s not that bad actually. One can even write legit code and still be able to read it afterwards. I was positively surprised. Seriously.

So after a few trial an errors I was able to launch the local instance of DDG with the command duckpan serve and display a dummy text.

Now it’s time to start coding. I elected to work in a TDD fashion, as much as I could. The DDG/Codio environment is great but you have to restart your duck after each modification, which is somewhat slow. It’s way faster to launch your unit tests. TDD has many advantages beyond that anyway, and I grew more confident my Perl code was actually working as I intended.

Test a lot and pay attention to the details. The world is watching, no pressure. People will review your code. Show them the best you can as a courtesy.

Then, when you’re ready… It’s time to create your pull request.

From here, the outcome is totally dependent on the feature and how you implemented it. Someone pointed me to a project library that I could use to for extra consistency. Then there was some discussion on the design. I changed things here and there, improving the original version. At some point, there was some confusion on a suggestion. That can happen, we’re not talking face to face. Later, it got to a point were additional changes were not improving the situation. It meant we were done.

About Perl: on DDH, it’s okay if your code does not feel “perlish”. They don’t expect everybody to have extended PERL knowledge. In fact, it’s quiet the opposite. As long as your code is clean and correctly structured, you should be fine, even if you haven’t used the relevant Perl tricks. I received several suggestions to apply interesting Perl idioms of course, and I applied them to my code. Contributing is also about learning.

Hopefully your PR is closed and approved. Just wait for it to become live… Then pat yourself on the back for a job well done :-D

It wasn’t my first time

Truth be told, I had already implemented another goodie earlier. But I failed to report I was working on it: before committing myself, I wanted to make sure I was actually going to do it. And guess what? Someone else issued a pull request just a few hours before me on the same idea!

What happens in that case? On a not-so-nice project, committers yell at you for the wasted time and effort, discard one of the PR, and everybody is frustrated. Here, @moollaza asked us what to do. The “other guy”, @jarmokivekas, suggested to take my code, but I had no shame to admit his was better. I suggested to take @jarmokivekas ’s version, and rip off the extra features and additional checks that were present only in mine. No ego fight. Code was reviewed, improved, and I participated in the tests. Both of us are listed as contributors. It’s live here.

Like I told you, it is a nice project and an excellent place to start if it’s your first time.