A number of recent threads have made it clear that we have a fair amount
of unspoken etiquette about how we do things around here, and the fact
that it is unspoken can be confusing to newcomers and old-timers alike.
Looking at a few other apache project web sites, they often seem to have
a page or two devoted to documenting their project etiquette. I think
this would be a good thing for us to have as well, and I've taken the
liberty of trying to seed this effort with some content.
I think there are some obvious places where it would make sense to
formalize some of this etiquette into some lightweight process, e.g.
having maintainers files in svn, having a sandbox for new code
contributions, etc, however this text is *not* intended to be a proposal
for that sort of thing, merely an attempt to put into words what I
believe most of us consider to be the status quo wrt the unspoken
etiquette of the project.
Of course the problem with unspoken etiquette is that we might not all
have the same concept of what it actually is, so please let me know if
you disagree with something I've written or you think something
important is missing.
--Rafael
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, and
even those developers who are familiar with most of the components
may not have time to be on the hook as a maintainer for more than a
few.
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.
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 potentially socially awkward, and
certainly slower process of telling someone that they got some part
of it wrong. It is, however, very necessary to ensure that those who
submit patches have every opportunity to learn what they need to
know in order to eventually become a valued qpid committer.
In that spirit, here are a few guidelines for dealing with patch
submissions:
- Make the submitter produce the final patch(s) as applied to the
tree. The submitter must have the opportunity to know what it
takes to produce a patch that needs little or no rework, because
the ability to produce such patches will ultimately play an
important role in becoming a qpid committer.
This may involve making requests for trivial updates to the
patch. If the submitter is serious about becoming a qpid
committer, then such requests are necessary to ensure that they
are familiar with subtle yet important aspects of the code,
stylistic conventions, etc. Remember if a submitter becomes a
committer, there will be no opportunity to fix up their work
before it goes into SVN.
- Make sure the submitter is familiar with project etiquette. It
might be easy to mistake requests for trivial updates to a patch
as rude or demeaning. This can be avoided if the submitter is
familiar with the reasons for such requests.
- Use your judgment. A one-time patch from someone who is clearly
not interested in becoming a committer may need nothing more
than a polite thank you regardless of the content. When in
doubt, don't hesitate to ask people what their intentions are.
- 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 we shouldn't give that impression to
patch submitters.
Big Ideas:
Every so often someone has a Big Idea that they get excited about
and want to go do. Because this is a Big Idea, it has some impact on
the overall project, and so 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. The resulting hubbub
usually wastes a good chunk of everyone's time, potentially wastes
all the time spent on the Big Idea, and engenders bad feelings all
around.
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. Just
because you hijacked some other thread and ranted about how
things should be, doesn't mean it's clear you intend to go off
and make them that way. 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
come hell or high-water, don't try to couch this with words like
"refactorize". If X is going to object, better that (s)he do so
sooner rather than later.
If you think features A, B, and C could be implemented more
simply and robustly by killing feature C that nobody cares
about, and switching around B and A, make sure you call out that
you intend to kill feature C.
Even if you're going to write an Atari emulator, and you're 100%
sure that it won't change or overlap with anything in the rest
of the project, some people may still have funny ideas about it
not being aligned with the goals of a messaging project, so 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
bit of this, it turned out this way, here is an
example/proof-of-concept/demo you can go play with, 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
clumsily describe it in words now and then 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 if you haven't been
around forever, then people may not trust you to be there when
the bugs start rolling in.
- 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.
- The bigger your idea is, the more time you should spend on the
proposal, and the more effort you should put into ensuring that
you get positive responses.
No matter how incredibly excellent your proposal is, nobody commits
to buying into the result of a large effort based on the initial
proposal, so 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 example/proof-of-concept/demo 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.
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 just in case someone has been hiding
under a rock for a while, 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.
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscr...@qpid.apache.org
