Mercurial > public > pelican-blog

comparison content/Coding/007-subversion-contrib.rst @ 4:7ce6393e6d30

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