Qpid Project Etiquette Guide

Purpose

This guide, written by Rafael Schloming, gives both Qpid committers and submitters a useful introduction to project etiquette, shedding light on how we do things & why. Following this etiquette makes the path to righteousness less long and winding !

Maintainers

The Qpid project consists of a number of major components spread across almost as many different languages. Thus it is rare for qpid committers to be experts in every single area of the project.

As such it is expected that qpid committers make some effort to reach out to their teammates before directly modifying components that are outside their chosen areas.

You should use the dev list to reach out to Qpid developers and comment on any JIRAs you're progressing.

Patch Submission

As a committer it can be difficult to decide whether/how to provide feedback when someone submits a patch. Often it is tempting to just fix up the patch and avoid the slower and sometimes awkward process of telling someone that they got some part of it wrong.

However, it is necessary to ensure that those who submit patches get to learn what they need to know in order to become a valued qpid committer.

In that spirit, here are a few guidelines for contributing patch submissions and how we handle them:

• Submitters should produce the final patch(s) as applied to the tree. Producing a patch that needs little or no rework is a key skill for a qpid committer.
• Maintainers may make requests for 'trivial' updates to the patch. Such requests are vital to ensuring that contributers get familiar with subtle yet important aspects of the code, stylistic conventions, etc.
• Make sure the submitter is familiar with project etiquette so they understand why we make seemingly trivial requests. We'll ask new contributers to read this etiquette info for that reason !
• A one-time patch from someone passing through may need nothing more than a polite thank you regardless of the content. If a submitter does aim for committership, best to make it plain you're planning to stay around on the project.
• Break up unrelated changes. It wouldn't be considered correct for a committer to glom together too many unrelated changes within a single commit, and so we won't commit this kind of patch from submitters.
• You need a JIRA for any patch to be attached to, which should accurately describe the change.

Big Ideas

Every so often someone has a Big Idea that they get excited about and want to go do. They generally mail the list about it to give people the opportunity to comment, and then when nobody says anything they go off and do it.

Fast forward six months later they commit/merge/enable/publish the result of their Big Idea, and suddenly everyone understands the full implications, and not everyone is happy.

Guidelines

So, here are a few guidelines for making sure this doesn't happen, starting with how to write a good proposal for a Big Idea:

• Make sure your proposal is recognizable as a proposal. An easy way to avoid ambiguity is to start a new thread for your proposal and stick "proposal" somewhere in the subject.
• Understand who and what your proposal effects, and make this clear. If you think X's implementation of Y doesn't deserve to live and you're going to rewrite the whole thing from scratch then make this very clear so X can object sooner rather than later.
• Make sure you call out loudly that you intend to kill feature A, even if you think no-one on earth should care.
• Even if you're going to write an Atari emulator, and you're 100% sure that it won't overlap with anything in the rest of the project, make sure you understand how and why it relates to the rest of the project in general, and make that clear.
• Be concrete. Often a proposal of the form "hey, I did a little of this, here is a proof-of-concept, I'd like to do it for real now" is far more effective than a proposal of the form "hey, I have this vague idea about this, I'm going to vaguely suggest it would be good if someone did it".
• Talk about the long term implications of your proposal. If it's code then someone needs to maintain it, and committers will expect this to be you. Make clear your intentions.
• Never assume silence implies complicity, more likely it means people didn't understand the implications of your proposal, or didn't have time to figure out why they didn't like it. Ask again !
• The bigger your idea is, the more time and effort you should spend on the proposal, and ensuring that you get positive responses and deal with the comments and feedback provided in your actual implementation.

Talk early, talk often

No matter how incredibly excellent your proposal is, there is going to need to be some discussion before the result of your Big Idea is blessed. Here are some things you can do to help that discussion go smoothly:

• Make frequent progress reports. Every hour/day/week/month you spend working without telling people what you're doing is an hour/day/week/month of your time that you risk wasting.
• Define milestones and make them visible to the rest of the project. Just like a concrete proof-of-concept can help a proposal, it helps to give people a concrete look at what you're doing while it's in progress. This can go a long way towards avoiding surprises.

And finally .....

When the time does come to commit/merge/enable/publish your Big Idea, it really shouldn't be a surprise to anyone if you've followed the steps up until now, but make sure you let people know in advance by making note in your final few progress reports of when you expect to be finished, and sending a note to the dev list a day or so before you flip the big switch.