focus for this week: Why don't birds fly backwards ?
>1.1 mio views (popular pages, total: 2,030)
Open Advice/Writing Patches
Writing Patches
- by Kai Blin
- in: Open Advice
This text is available under the CC-BY-SA license. (see also: Open Advice/Info)
Contents |
Writing patches and submitting them often is the first real interaction you can have with an Open Source project. They are the first impression you give to the developers there. Getting your first patches “right”, however that is judged by the particular project you are contributing to, will make your life much easier.
The exact rules on what the patch should look like, how you need to send it to the project and all the other details will probably vary with every project you want to contribute to. I have found that few general rules hold pretty much all the time, and that is what this essay is about.
How to get things wrong
This book is about “things we wish we had known when we got started”, so let me get started with the story of my first patches. I first got involved in real coding during the Google Summer of Code 2005. The Wine project had accepted me to implement NTLM crypto based on some Samba-related tool. Wine is a single-committer project, meaning that only the lead developer, Alexandre Julliard, has commit access to the main repository. Back in 2005, Wine still was using CVS as its version control. When the project started and I got the email that I was accepted, I got hold of my mentor on IRC and got to work.
Coding away happily, I got the first features implemented. I produced a patch for my mentor to review. In the olden CVS days, you had to provide all the diff options manually, but I had read up on that part. cvs diff -N -u > ntlm.patch and I had the file I could send to my mentor. Actually this is one thing I did get right, and the first thing you should consider when you prepare a patch. The normal output from the diff command might be easier to read for a computer, but I never met a human who actually preferred the normal output over the unified diff output. Switched on by the -u flag, this makes diff use the + + + and − − − notation.
For example, the following diff is the result of teaching the Python ”Hello, world!” example program to greet the world in Swedish.
- diff --git a/hello.py b/hello.py
- index 59dbef8..6334aa2 100644
- --- a/hello.py
- +++ b/hello.py
- @@ -1,4 +1,4 @@
- !/usr/bin/env python
- vim: set fileencoding=utf-8
- -print "Hello, world!"
- +print "Hallå, världen!"
The line starting with - is the line being removed, the one starting with + is the one being added. The other lines are helping the patch tool to do its job.
My newly created unified diff was sent to my mentor, who gave me a review and lots of things I could change. I fixed that stuff, and sent him a new diff shortly after. The code–review cycle continued for the whole duration of GSoC, with my patch growing and growing. When the pencils down date arrived, I had a huge monster patch with all my changes in there. Naturally I had a really hard time getting that patch reviewed, let alone committed. In the end, Alexandre refused to look at the patch further before I split it up. Wine policy requires that patches are small logical steps adding functionality. Each patch needs to do something useful and compile.
Now, splitting an existing huge patch up in pieces that individually make sense and compile is a lot of work. It was even more work because the only way I knew this could be done was to write a small patch, create the diff, get that committed, update my local checkout and then write the next small patch. Shortly after I started sending my first small patches, Wine went into a one month feature freeze leading up to the 0.9.0 beta release. I was sitting on my next patch for a month before I could continue, and I eventually got my last patch in in November. I was totally frustrated with the whole experience and decided I did not want to deal with the Wine community anymore.
My frustration held up until people who were actually using my code were starting to ask questions about it in February 2006. My code was actually useful! They wanted more features as well. When Google went on to announce it would be doing GSoC again in 2006, my plans for the summer were clear. Now that Wine had switched to git in December 2005, I knew I would not be held up by possible code freezes, as I finally could create all my small patches locally. Life was good.
It wasn’t until I stumbled over a git frontend (called porcelain[1] in git-speak) that emulated the “quilt” behavior that I learned that there were tools that could have made my life easier even in 2005.
How NOT to get things wrong
After my tale of how I managed to get things wrong with regard to sending patches, let me continue with a few tips to avoid the pitfalls.
Patch submission guidelines
The first tip I have is to read up on any patch submission guidelines the project you want to contribute to might have. Those should actually be consulted before you start coding, along with any coding style guidelines the project has.
Unified diffs
Even if not covered in the patch submission guidelines explicitly, you really, really want to send unified diff output. I have yet to meet a project that prefers the non-unified output of diff. Unified diffs make reviewing the patch so much easier. It is no accident that most modern version control programs automatically use that format in their diff command.
Use distributed version control
Speaking of modern version control, you will want to use a DVCS to work on the code locally. Git or Mercurial are the most popular choices there, Bazaar might be worth a look as well. Even if the project you want to contribute to still uses a centralized version control, being able to commit your changes iteratively is a great thing. All of the mentioned distributed version control tools should be able to import commits from SVN or CVS. You could go and learn quilt, but seriously, the future is in the field of distributed version control.
Small patches, doing one thing at a time
When I have to review patches, patches that are too big or that try to do many things at once are really annoying to deal with. Patches doing only one thing at a time are easier to review. Eventually, they will make your life easier when you finally need to debug the mistakes both the author and the reviewer of the patch missed.
Track your patch
After you have submitted your patch, keep an eye on the communication channels of the project and on your patch. If you have not gotten any feedback for a week, you should politely ask for feedback. Depending how the project handles patch submissions, a patch might get lost in the noise. Do not expect to get your patch committed in the first iteration. It usually takes a couple of tries to get used to the style of a new project. As a first-time contributor, nobody will blame you for this, provided you get most of the things right. Just make sure that you fix all of the things the developers indicated and send a second version of the patch.
Conclusion
Writing good patches is not hard. There are a couple of things to consider, but after writing a couple of them you should be on top of those. A modern (distributed) version control system and the workflow you get using it actually take care of most of the things I mentioned.
If you remember nothing else, remember this...
- Use a distributed version control system to manage your patches
- Write patches changing code in small, self-contained steps
- Follow the existing coding conventions
- Respond to comments on your patch promptly
The above guidelines should help you to do most if not all things right when submitting your first patches. Happy coding.
about the author
Kai Blin is a computational biologist searching for antibiotics in his day job, both at the computer and in the lab. He feels very happy that he gets to release the software developed at work under Open Source licenses. Living in the lovely southern German town of Tübingen, Kai spends some of his evenings at the computer, programming for the Samba project. Most of his remaining spare time is spent at the theatre, where Kai is active both on stage as well as building props, stage and handling other techie things backstage.
notes
