You need good tools to do a good job.
Even the best tool in the hand of a novice is a club.
I’m quite fond in improving the tools I use. And that’s why I started getting involved in Gentoo, Libav, VLC and plenty of other projects.
I already discussed about lldb and asan/valgrind, now my current focus is about patch trackers. In part it is due to the current effort to improve the libav one,
Before talking about patches and their tracking I’d digress a little on who produces them. The mythical Contributor: without contributions an opensource project would not exist.
You might have recurring contributions and unique/seldom contributions. Both are quite important.
In general you should make so seldom contributors become recurring contributors.
A recurring contributor can accept to spend some additional time to setup the environment to actually provide its contribution back to the community, a sporadic contributor could be easily put off if the effort required to send his patch is larger than writing the patch itself.
Th project maintainers should make so the life of contributors is as simple as possible.
Patches and Revision Control
Lately most opensource projects saw the light and started to use decentralized source revision control system and thanks to github and many other is the concept of issue pull requests is getting part of our culture and with it comes hopefully a wider acceptance to the fact that the code should be reviewed before it is merged.
In a decentralized development scenario new code is usually developed in topic branches, routinely rebased against the master until the set is ready and then the set of changes (called series or patchset) is reviewed and after some round of fixes eventually merged. Thanks to bitbucket now we have forking, spooning and knifing as part of the jargon.
The review (and merge) step, quite properly, is called knifing (or stabbing): you have to dice, slice and polish the code before merging it.
During a review bugs are usually spotted as well way to improve are suggested. Patches might be split or merged together and the series reworked and improved a lot.
The process is usually time consuming, even more for an organization made of volunteer: writing code is fun, address issues spotted is not so much, review someone else code is much less even.
Sadly it is a necessary annoyance since otherwise the errors (and horrors) that would slip through would be much bigger and probably much more. If you do not care about code quality and what you are writing is not used by other people you can probably ignore that, if you feel somehow concerned that what you wrote might turn some people life in a sea of pain. (On the other hand some gratitude for such daunting effort is usually welcome).
Pull request management
The old fashioned way to issue a pull request is either poke somebody telling that your branch is ready for merge or just make a set of patches and mail them to whoever is in charge of integrating code to the main branch.
git provides a nifty tool to do that called
git send-email and is quite common to send sets of patches (called usually series) to a mailing list. You get feedback by email and you can update the set using the
--in-reply-to option and the message id.
Platforms such as github and similar are more web centric and require you to use the web interface to issue and review the request. No additional tools are required beside your git and a browser.
gerrit and reviewboard provide custom scripts to setup ephemeral branches in some staging area then the review process requires a browser again. Every commit gets some tool-specific metadata to ease tracking changes across series revisions. This approach the more setup intensive.
Pro and cons
Mailing list approach
Testing patches from the mailing list is quite simple thanks to
git am. And if the reply-to field is used properly updates appear sorted in a good way.
This method is the simplest for the people used to have the email client always open and a console (if they are using a well configured emacs or vim they literally do not move away from the editor).
On the other hand, people using a webmail or using a basic email client might find the approach more cumbersome than a web based one.
If your only method to track contribution is just a mailing list, gets quite easy to forget which is the status of a set. Patches could be neglected and even who wrote them might forget for a long time.
Patchwork tracks which patches hit a mailing list and tries to figure out if they are eventually merged automatically.
It is quite basic: it provides an web interface to check the status and provides a mean to just update the patch status. The review must happen in the mailing list and there is no concept of series.
As basic as it is works as a reminder about pending patches but tends to get cluttered easily and keeping it clean requires some effort.
The web interface makes much easier spot what is pending and what’s its status, people used to have everything in the browser (chrome and mozilla could be made to work as a decent IDE lately) might like it much better.
Reviewing small series or single patches is usually nicer but the current UIs do not scale for larger (5+) patchsets.
People not living in a browser find quite annoying switch context and it requires additional effort to contribute since you have to register to a website and the process of issuing a patch requires many additional steps while in the email approach just require to type
git send-email -1.
The gerrit interfaces tend to be richer than the Github counterparts. That can be good or bad since they aren’t as immediate and tend to overwhelm new contributors.
You need to make an additional effort to setup your environment since you need some custom script.
The series are tracked with additional precision, but for all the practical usage is the same as github with the additional bourden for the contributor.
Plaid is my attempt to tackle the problem. It is currently unfinished and in dire need of more hands working on it.
It’s basic concept is to be non-intrusive as much as possible, retaining all the pros of the simple git+email workflow like patchwork does.
It provides already additional features such as the ability to manage series of patches and to track updates to it. It sports a view to get a break out of which series require a review and which are pending for a long time waiting for an update.
What’s pending is adding the ability to review it directly in the browser, send the review email for the web to the mailing list and a some more.
Probably I might complete it within the year or next spring, if you like Flask or python contributions are warmly welcome!