How I've started to contribute to open source

A couple of weeks ago, I read a post by Brandon Hays called ‘“Why I still don’t contribute to open source":http://brandonhays.com/blog/2011/05/03/why-i-still-dont-contribute-to-open-source/’ wherein Brandon lays out his reasons for not yet having contributed to any OSS projects. To reiterate Brandon’s points:

  1. There’s no certification, ceremony, or merit badge that says, ’you’re ready to contribute to OSS’.
  2. It’s not obvious where to start.
  3. Guidelines often make a maintainer’s life easier, and mine harder.
  4. Open source is for people who are better at this than me.
  5. Trying to contribute and failing makes me feel stupid.
  6. There’s no time.
  7. It’s pretty lonely.

I found Brandon’s article interesting because I can definitely relate to a lot of what he says.

How do I know I’m ready to hack on an open source project? And if I’m not ready but jump in anyway, won’t I potentially just be broadcasting my stupidity across the Interwebs for all to see? How do I know where to start? The code base seems so intimidating and I know nothing about it. Are any hazing rituals involved? Those guys are so much better at hacking code than I’d be after ten lifetimes, how the fuck did they get so smart? Or am I just really retarded? I’ve got my own stuff I want to work on. All these sentiments I’ve felt at one time or another.

But recently, I’ve started contributing to open source projects anyway.

The rest of this post is devoted to a couple of small case studies in my open source contributions and the lessons that I have drawn from them, hopefully for the benefit of those of us who may be interested in beginning to contribute to OSS.

Enki and HTML 5, etc.

A few months ago, I decided to start a blog. Being partial to a bit of Ruby and Rails, I went looking for a solution based on these technologies and finally came to rest on Enki by Xavier Shay. Xavier’s design philosophy appealed to me, I liked the straight forwardness of Enki. I can also credit my experience with Enki as being probably the largest single factor that got me comfortable with Git and GitHub.

As part of sorting out my own blogging needs using Enki as a base, I felt like experimenting with a couple of features:

Participating on the Enki mailing list, I noted that Xavier mentioned he was looking for some help to convert Enki to HTML5. This sounded like something I could tackle, so I put my hand up for it and a little while later had some changes ready for review. This work wasn’t hard, but it was pretty extensive and also required that Xavier update some of the Enki feature/spec files to tidy things up.

A few months later, feeling encouraged by the reception of my previous contributions, I took on an open issue for Enki and submitted a patch to close it shortly after.

Contributing to Enki has been enjoyable. I don’t think I could have found a better introduction to open source contribution than this small foot print blogging system if I had planned to find an OSS project to contribute to from the beginning. As it was, I really hadn’t been aiming to contribute to any OSS project, I was just looking for a blogging platform.

Thanks to Xavier Shay for writing Enki in the way he has and for being receptive and open to contributions from n00bs. His focus on creating a blogging app for developers that relies strongly on version control and hacking code over predefined preference user interfaces and plugin systems is what encouraged me to contribute to this project almost without realising I was doing it at first.

paypal_adaptive and SSL certificate verification

I’m currently working on a pet project where I’m using the Adaptive Payments API from PayPal. My project is a Rails app so I had a look around to see if anyone has done any Ruby based work with Adaptive Payments that I could build on top of. I found a few options, but eventually settled on the paypal_adaptive gem by Tommy Chheng. Tommy describes it as a light wrapper for PayPal’s Adaptive Payment API. I chose it because it appeared to be one of the newer Ruby API wrappers for Adaptive Payments so there was a good chance it was still being actively maintained/developed1. And being the light wrapper that it is, it didn’t seem too hard to get my head around the code base.

So I installed the gem and went to work. But not too long into integrating paypal_adaptive into my project – while testing my first remote API call to PayPal – I was hit by this error:

1
SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed

A little googling revealed that this exception is caused by Net::HTTP (the component of the Ruby standard library that paypal_adaptive uses to make remote calls to PayPal) not being able to find a root certificate bundle with which to verify SSL certificates (Net::HTTP can also handle HTTPS calls and that’s what paypal_addaptive was trying to do). But I could find no mention of this issue in relation to the use of paypal_adaptive. Why was I hit with this issue and not other users of Tommy’s gem, I wondered. I believe the likely answer was because I am using Ruby 1.9.2 and TLS/SSL connections done through Net::HTTP in Ruby 1.9.x by default try to verify SSL certificates whereas Ruby 1.8.x by default does not. So anyone using paypal_adaptive with Ruby 1.8.x wouldn’t have unknowingly run into this issue.

There’s a fair bit of information online about how to get around the ‘certificate verify failed’ error. Some recommend just telling Ruby not to verify SSL certificates by setting the ‘verify_mode’ attribute of your Net::HTTP object to ‘OpenSSL::SSL::VERIFY_NONE’. But there’s good reason why Ruby 1.9.x changed the default behaviour. If you’re not verifying the SSL certificate of the party that you’re connecting to, then you’re only getting part of the benefit of using TLS/SSL. You’re still getting the encrypted data transfer but you’re not verifying that the the party on the other end of that encrypted data transfer is who you think it is. So for me ‘OpenSSL::SSL::VERIFY_NONE’ really wasn’t an option. A better solution is to let Ruby know where it can find a root certificate bundle. But how best to do this considering that the relevant code is inside the paypal_adaptive gem?

Time for some open source contribution! But before anything else, I wanted to do some recon. I sent Tommy an email discussing this issue, asking what he thought might be the best way to tackle it and whether he’d be interested in a patch from me. After a couple of emails back and forth we’d agreed on a plan of attack and I told Tommy that he could expect a pull request from me on GitHub once I’d got something worth looking at.

I put aside my pet project for a little while and got to work on modifying paypal_adaptive to include SSL certificate verification. After my first pull request was accepted, I realised that I had managed to introduce a minor bug in the new SSL certificate verification functionality, and I later submitted another pull request to fix the issue. Broadcasting my stupidity across the Interwebs? Check.

I am now back to my regularly scheduled programming on my own project with the new and improved SSL certificate verification support in paypal_adaptive. Thanks to Tommy Chheng for writing paypal_adaptive and for being a responsive maintainer.

Lessons learnt

So what can I draw from the above case studies?

GitHub rocks!

GitHub works pretty damn well for me. Once I’d gotten a basic familiarity with Git it was only a small step further to get familiar with GitHub. After which, a lot of the uncertainty and potential friction around the practicalities of contributing to any open source project that makes use of Git and GitHub are all neatly removed. Just fork, clone, hack, push, send pull request.

I sometimes get the feeling that some developers wonder what all the fuss is about. After all, people have been hacking code and contributing to open source long before GitHub and its ilk hit the scene. Github is certainly not a necessity, but I can only speak for myself when I say that GitHub has made a real difference in my ability to feel like I’m able to contribute to open source. The guys behind it have done a great job and they deserve all their success2.

So the first lesson I might draw would be to find a community enabler like GitHub. If you prefer Mercurial there’s BitBucket. The centralised nature of older version control systems like Subversion and CVS don’t seem to lend themselves well to such decentralised development as one sees with Git or Mercurial but I gather there are ways to bridge older systems at least.

You will make mistakes

Many introverted people – counting myself as one – really don’t like to look silly, especially not in public. We can be overly self conscious and engaging in activities that contain the promise of some degree of public humiliation does not usually sit well. It’s very likely that you will make mistakes from time to time when contributing to open source projects and yes, those mistakes will be publicly visible. But it’s pretty damn hard to learn anything without making any mistakes.

I wish there was some secret weapon I could provide here to get deftly past this fear of failure and ridicule. I have none. I can only observe that as I have grown older and more confident within myself, my ability to be comfortable with risking failure in pursuit of my goals seems to have grown, maybe for some people it just takes some time. It certainly helps not to take myself too seriously, a sense of humour about my short comings has helped me when I can summon it. Something else that tends to put things into perspective for me in an inspiring way is an excerpt from one of Theodore Roosevelt’s speeches that has come to be known as ‘The Man in the Arena’:

It is not the critic who counts; not the man who points out how the strong man stumbles, or where the doer of deeds could have done them better. The credit belongs to the man who is actually in the arena, whose face is marred by dust and sweat and blood; who strives valiantly; who errs, who comes short again and again, because there is no effort without error and shortcoming; but who does actually strive to do the deeds; who knows great enthusiasms, the great devotions; who spends himself in a worthy cause; who at the best knows in the end the triumph of high achievement, and who at the worst, if he fails, at least fails while daring greatly, so that his place shall never be with those cold and timid souls who neither know victory nor defeat.

It’s true, scratch your own itch

I realise this isn’t a new revelation, but all my open source contributions to date have been of the ‘scratch your own itch’ type. This really does seem like the most natural way to get into open source contribution. As I found with Enki, doing it this way I almost didn’t notice the transition between using the app and contributing to it. If you can find a personal itch to scratch then my experience suggests that this is the easiest way to start.

Talk to the maintainer(s) first

I have so far always spoken to the project maintainer before contributing anything to their project. I’m not sure how just shooting pull requests at people out of the blue works, but my guess is it doesn’t work as well. The maintainer knows their project best and I’ve found it’s important to clearly understand what their perspective is up front. When contributing to paypal_adaptive, Tommy Chheng actually ended up suggesting what I thought was a much better approach to the SSL certificate verification issue than the one I originally brought to him and from there we built a little on each others ideas to reach the final patch.

In communicating with the maintainer I usually come from a few assumptions:

  1. The maintainer is a smart person
  2. The maintainer is a busy person
  3. The maintainer is a person

Based off these assumptions I then try to keep my messages brief, to the point and respectful.

I sometimes see in myself a reluctance to contact certain developers, particularly those who have some degree of Internet celebrity about them. I assume this reluctance partially stems from the same kind of ‘star struck’ reaction that might be common in the off-line world when meeting or interacting with someone whose qualities you admire. But beyond this, the thought that these people must get a lot of mail and might just be sick of talking to strangers about their silly little issues can weigh on my mind also. What I have found is that if I just stick to the above assumptions then my interactions (even with celebrity developers, as minor as those interactions may be) tend to go pretty smoothly.

There’s another reason why I like to contact maintainers first and it’s kind of the same reason why I tend to contact online stores before placing an order with them. I want to scope them out and see how responsive they are and what their style of communication is. In the case of paypal_adaptive, had I never heard back from Tommy Chheng, I then would have known that the better option was probably just to fork his project and continue on my own (see GitHub rocks!).

Start small and easy

I’ve deliberately tried to start off making small and easy contributions. I’ve also concentrated on contributing to projects that are based on technologies that I already have some familiarity with (Ruby, Rails). This way the organisation of the code base is not entirely foreign to me, I have an existing frame of reference.

I don’t have a lot of time and I do have my own stuff that I’m working on, so small and occasional contributions are really all I can commit to for the foreseeable future. I’m not apologising for this and I don’t feel that anyone is asking me to.

Conclusion

I hope this helps someone to feel like they’re ready to contribute to open source, even if it’s in the small ways that I have now managed. In my niche of the IT industry (i.e. web development) there’s so much great open source software out there that we all rely on day in, day out and it feels good to give a little something back.

OSS can look like a shark tank to newbies, but if you take it slow and steady, I think most of the sharks can be avoided.

1 Also, being a Ruby programmer I’m fascinated by anything new and shiny, while simultaneously heedless of any backwards compatibility issues my penchant may engender.

2 I feel some acknowledgement should also go to Linus Torvalds for developing Git its self. But it’s not like any of us will forget that guy’s contributions regardless of what happens from here on out.

  1. Javin says:

    In my opinion one should participate on OSS it not just improve your skills but also something to give up community cause if we already use OSS, though easier said than done it has its own challenges as you mentioned in first para but I must appreciate your encouragement to promote this.

    http://javarevisited.blogspot.com/2011/05/top-10-tips-on-logging-in-java.html

  2. Chris Kimpton says:

    Cool - thanks for sharing. I do a little here and there, and this might encourage me to do a little more :).

  3. Gaelian says:

    @Chris Kimpton: No worries, glad you found some value.

  4. Casey Strouse says:

    Great article. I'm a Ruby programmer too and have been reluctant to make contributions for the same reasons. I sent some emails the other day to project maintainers to see if I could get my feet wet with some minor issues and with improving documentation. I feel that getting to know the people involved through non-technical means might make it easier to contribute code in the future.

  5. allenwei says:

    With github contribute become very easy. Just fork the repository and send pull request.

    We can start from easiest issue, like fix typo in documentation.

  6. Paul says:

    Thanks for the encouragement

  7. roger says:

    yo, web stuff (html, etc) isn't real open source. it's just worthless markup.

    start contributing to real projects!

  8. Lukasz Badura says:

    Thank you for this inspiring post. Do you contribute to projects based on a technology stack that you are little familiar with (to learn new things) ? Or perhaps it's necessary to gain some fluency first ?

  9. Gaelian says:

    Thanks for the encouraging comments, people. Sorry I couldn't reply more quickly, I needed to get some sleep to be ready for work today. :)

    @Lukasz Badura: I think a little of both. I've found contributing to projects that are based on technology stacks I'm familiar with is less intimidating, certainly some fluency is helpful up front. But it's not like I don't learn anything new while contributing to such projects.

  10. madlep says:

    Just like to add that Xavier is a super nice guy and plays well with others in person as well :)

  11. Ashwin Raghav says:

    Nice one m8 :)

  12. Raffi Mohammed says:

    Nice article.

  13. Stultus says:

    Great Article!! Thank you !! :)

  14. Magesh says:

    Awesome!
    Thanks for sharing it

  15. Brandon Hays says:

    Thanks for this response, it's well-reasoned, kind, and instructive. It's true that the fact is, you have to jump into the pool at some point, and there's no way around it.

    My problem, looking back, is that each time I tried to start, I was biting off more than I could chew, which is an immensely frustrating experience. OSS contribution doesn't really have a mechanism for making sure you aren't getting in over your head, or a way to "bow out gracefully" if you are.

    Thanks again for taking the time to share your thoughts, I for one found it inspiring and will definitely be thinking on this.

  16. Gaelian says:

    @Brandon Hayes: I'm pleased to see my post has somehow made it to you across the digital ocean, Brandon.

    I'm also pleased you don't seem to mind me mentioning you here and I'm happy that you found some interest in my musings. I really meant it when I said that I can relate to a lot of what you said in your post, it's taken me a long time (maybe too long :P) just to feel confident enough to start contributing in these small ways, but it feels really good to have done so.

    Start small and easy. That's my current mantra when it comes to OSS contributions.

  17. rps says:

    "But it's pretty damn hard to learn anything without making any mistakes."

    So true! Inspiring post. I can tell that you worked hard on it and I thoroughly enjoyed it.

    It seems to me that as long as people are actively looking for ways to contribute to open source projects, everything else will work itself out, so don't worry about it. Brandon Hays of the world: keep at it, you'll get there!

    rs.io

Post a comment

Name or OpenID (required)


(lesstile enabled - surround code blocks with ---)