bgneal@4: Contributing to open source - a success story and advice for newbies
bgneal@4: ####################################################################
bgneal@4: 
bgneal@4: :date: 2011-06-23 21:45
bgneal@4: :tags: Subversion, OpenSource
bgneal@4: :slug: contributing-to-open-source-a-success-story-and-advice-for-newbies
bgneal@4: :author: Brian Neal
bgneal@4: 
bgneal@4: Recently, my team at work found a `bug in Subversion`_, I submitted a patch, and it
bgneal@4: was accepted!  This was very exciting for me so I thought I would share this
bgneal@4: story in the hopes of inspiring others to contribute to open source projects.
bgneal@4: It may not be as hard as you might think!
bgneal@4: 
bgneal@4: The Bug
bgneal@4: =======
bgneal@4: 
bgneal@4: We use Subversion_ at work for revision control. My colleague and I were trying
bgneal@4: to merge a branch back to trunk when we ran into some strange behavior. We make
bgneal@4: use of Subversion properties, which allow you to attach arbitrary metadata to
bgneal@4: files and directories. Our project has to deliver our source code and
bgneal@4: documentation to the customer in a required directory format (can you guess who
bgneal@4: our customer is?). However not all files need to be sent to the customer. To
bgneal@4: solve this problem we use a simple "yes/no" delivery property on each file to
bgneal@4: control whether it is delivered or not. Before making a delivery, a script is
bgneal@4: run that prunes out the files that have the delivery flag set to "no". 
bgneal@4: 
bgneal@4: When our merge was completed, many files were marked with having merge conflicts
bgneal@4: on the delivery property. Looking through the logs it was discovered that after
bgneal@4: we had made our branch, someone had changed the delivery property on some files
bgneal@4: to "yes" on the trunk. Someone else had also changed the delivery property
bgneal@4: independently to "yes" on the branch. When we attempted to merge the branch back
bgneal@4: to trunk, we were getting merge conflicts, even though we were trying to change
bgneal@4: the delivery property value to "yes" on both the trunk and branch. Why was this
bgneal@4: a conflict? This didn't seem quite right.
bgneal@4: 
bgneal@4: I signed up for the Subversion user's mailing list and made a short post
bgneal@4: summarizing our issue. I later learned that it is proper etiquette to attach a
bgneal@4: bash script that can demonstrate the problem. Despite this, a Subversion developer
bgneal@4: took interest in my post and created a test script in an attempt to reproduce our
bgneal@4: issue. At first it looked like he could not reproduce the problem. However another
bgneal@4: helpful user pointed out a bug in his script. Once this was fixed, the developer 
bgneal@4: declared our problem a genuine bug and created a ticket for it in the issue tracker.
bgneal@4: 
bgneal@4: The Patch
bgneal@4: =========
bgneal@4: 
bgneal@4: Impressed by all of this, I thanked him for his efforts and tentatively asked if
bgneal@4: I could help. The developer told me which file and function he thought the
bgneal@4: problem might be in. I downloaded the Subversion source and began looking at the
bgneal@4: code. I was fairly impressed with the code quality, so I decided I would try to
bgneal@4: create a patch for the bug over the weekend. We really wanted that bug fixed,
bgneal@4: and I was genuinely curious to see if I would be able to figure something out.
bgneal@4: It would be an interesting challenge and a test of my novice open source skills.
bgneal@4: 
bgneal@4: When the weekend came I began a more thorough examination of the Subversion
bgneal@4: website. The Subversion team has done a great job in providing documentation on
bgneal@4: their development process. This includes a contributing guide and patch
bgneal@4: submittal process. I also discovered they had recently added a makefile that
bgneal@4: downloaded the Subversion source code and the source for all of Subversion's
bgneal@4: dependencies. The makefile then builds everything with debug turned on. Wow! It
bgneal@4: took me a few tries to get this working, but the problems were because I did not
bgneal@4: have all the development tools installed on my Ubuntu box.  Once this was
bgneal@4: sorted, everything went smoothly, and in a matter of minutes I had a Subversion
bgneal@4: executable I could run under the gdb debugger. Nice!
bgneal@4: 
bgneal@4: I studied the code for about an hour, peeking and poking at a few things in the
bgneal@4: debugger. I used the script the developer wrote to recreate the problem. I
bgneal@4: wasn't quite sure what I was doing, as I was brand new to this code base. But
bgneal@4: the code was clearly written and commented well. My goal was to get a patch that
bgneal@4: was in the 80-100% complete range. I wanted to do enough work that a core
bgneal@4: developer would be able to see what I was doing and either commit it outright or
bgneal@4: easily fill in the parts that I missed. After a while I thought I had a solution
bgneal@4: and generated a patch. I sent it to the Subversion developer's mailing list as
bgneal@4: per the contributing guide.
bgneal@4: 
bgneal@4: The Wait
bgneal@4: ========
bgneal@4: 
bgneal@4: Next I began probably the worst part for a contributor. I had to wait and see if
bgneal@4: I got any feedback. On some open source projects a patch may languish for months.
bgneal@4: It all depends on the number of developers and how busy they are. My chances
bgneal@4: didn't look good as the developers were in the initial stages of getting a
bgneal@4: beta version of 1.7 out the door. It was also not clear to me who "owned" the
bgneal@4: issue tracker. On some projects, the issue tracker is wide open to the
bgneal@4: community. Was I supposed to update the ticket? I wasn't quite sure, and the
bgneal@4: contributing guide was silent on this issue. I eventually concluded I was not;
bgneal@4: it looked like only committers were using the tracker. Patches were being
bgneal@4: discussed on the mailing list instead of in the tracker. This is a bit different
bgneal@4: than some projects I am familiar with.
bgneal@4: 
bgneal@4: I didn't have to wait long. After a few days, the original developer who
bgneal@4: confirmed my bug took interest again. He looked at my patch, and thought I had
bgneal@4: missed something. He suggested a change and asked for my opinion. I looked at
bgneal@4: the code again; it seemed like a good change and I told him I agreed. I also
bgneal@4: warned him I was brand new to the code, and to take my opinion with a grain a
bgneal@4: salt. After running my change against the tests, he then committed my patch!
bgneal@4: One small victory for open source!
bgneal@4: 
bgneal@4: Final Thoughts
bgneal@4: ==============
bgneal@4: 
bgneal@4: So what went right here? I have to hand it to the Subversion team. They have
bgneal@4: been in business a long time, and they have excellent documentation for people
bgneal@4: who want to contribute. The makefile they created that sets up a complete
bgneal@4: development environment most definitely tipped the scale for me and enabled me
bgneal@4: to create my patch. Without that I'm not sure I would have had the time or
bgneal@4: patience to get all that unfamiliar source code built. The Subversion team has
bgneal@4: really worked hard at lowering the barrier for new contributors.
bgneal@4: 
bgneal@4: My advice to people who want to contribute to open source but aren't quite sure
bgneal@4: how to go about doing it:
bgneal@4: 
bgneal@4: - Spend some time reading the documentation. This includes any FAQ's and
bgneal@4:   contributor guides (if any).
bgneal@4: - Monitor the user and developer mailing lists to get a feel for how the
bgneal@4:   community operates. Each project has different customs and traditions.
bgneal@4: - You may also wish to hang out on the project's IRC channel for the same
bgneal@4:   reason.
bgneal@4: - When writing on the mailing lists, be extremely concise and polite.
bgneal@4:   You don't want to waste anyone's time, and you don't want to
bgneal@4:   be seen as someone who thinks they are entitled to a fix. Just remember you
bgneal@4:   are the new guy. You can't just barge in and make demands.
bgneal@4: - Ask how you can help. Nothing makes a developer happier when someone asks how
bgneal@4:   they can help. Remember, most of the people in the community are volunteers.
bgneal@4: - Open source can sometimes be "noisy". There will be people who
bgneal@4:   won't quite understand your issue and may hurriedly suggest an incorrect solution or give
bgneal@4:   incomplete advice. Study their responses and be polite. You may also wish to resist the temptation
bgneal@4:   to reply right away. This is especially hard when you are new and you don't
bgneal@4:   know who the "real" developers are. However you should assume everyone is trying to
bgneal@4:   help.
bgneal@4: - Finally, be patient. Again, most folks are volunteers. They have real jobs,
bgneal@4:   families and lives. The project may also be preoccupied with other tasks, like
bgneal@4:   getting a beta out the door. Now may not be a good time for a brand new
bgneal@4:   feature, or your bug may not be considered a show stopper to the majority of
bgneal@4:   the community.
bgneal@4: 
bgneal@4: A big thank-you to Stefan Sperling from the Subversion team who shepherded my
bgneal@4: bug report and patch through their process. 
bgneal@4: 
bgneal@4: I hope this story encourages you to contribute to open source software!
bgneal@4: 
bgneal@4: .. _bug in Subversion: http://subversion.tigris.org/issues/show_bug.cgi?id=3919
bgneal@4: .. _Subversion: http://subversion.apache.org/