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