policy -- the donut rule


Subject: policy -- the donut rule
From: Paul Rohr (paul@abisource.com)
Date: Tue Aug 21 2001 - 13:35:20 CDT


One of the oldest policies in the AbiWord development community has been
what's usually called the "donut rule":

  You break someone's build, you owe them donuts.

The two obvious exceptions are when:

  - you warn them what's happening and help them make any fixes, or
  - they've asked you to break it so they know what to fix.

This kind of self-discipline is unusual in many smaller development teams,
where it's often considered safe to assume that any other developer has the
same capacity you do to fix any problems that arise. Thus you'll find that,
for those teams, the source trees often *don't* build cleanly, and they
spend a *lot* of effort near release time just trying to get the product to
build.

We take more pride in our work than that. There are *so* many people who
could be working on this tree at any given time, that it's considered
incredibly rude to make them *all* stop working on their cool features just
to clean up a mess *you* made.

This policy becomes especially important when doing cross-platform work,
because any assumptions about the capacities of the toolchains and libraries
on other platforms are only valid after they've been tested.

If you find that your donut bill is getting out of hand, here are four
resources that can help:

1. http://www.abisource.com/tinderbox/
---------------------------------------
When it's up and running, Tinderbox shows the results of continuous attempts
to build the latest CVS sources on a variety of supported platforms. It can
even keep track of developers "on the hook" ... folks who've committed work
that hasn't yet been built cleanly on all platforms. When all columns are
green, then the tree builds and nobody's on the hook.

When it's red, somebody's in "donut danger", but by reading the errors and
warnings, you have the opportunity to clean up after yourself before anybody
calls you on it. ;-)
 
2. abi/docs/AbiSourceCodeGuidelines.abw
----------------------------------------
In addition to the usual stylistic stuff (braces, indents, etc.), this
document includes a number of battle-tested coding standards that help us
avoid compiler-specific headaches.

For example, in addition to mentioning this donut rule, there's also a
reference to the C++ Portability Guidelines document at www.mozilla.org --
ignore it at your peril! There are a bunch of busted compilers out there,
and a little defensive coding now is much easier than making treewide
modifications later to get an "easy" port building.

3. http://www.abisource.com/mailinglists/abiword-dev/00/March/0071.html
------------------------------------------------------------------------
When you implement a new dialog, you'll be doing the XP work, as well as the
work needed for your platform. While you're at it, be polite and go ahead
and stub out the dialogs on all the other platforms.

Not only does this prevent build breakage, but it's a useful opportunity for
you to communicate to folks on N other platforms what work you've left for
them to do. If Thomas wants the build to break on QNX, he can put a #error
in his dialog stub. ;-)

4. #ifdef
----------
When you have a big hunk of code that you'd like other developers to test,
they'll occasionally ask you to check it in behind a temporary #ifdef. That
way, instead of applying and reverting patches, they can just flip a switch
to test it. This is most useful for ongoing work on big hunks of code (like
Bidi support) that can't be managed any other way.

Paul



This archive was generated by hypermail 2b25 : Tue Aug 21 2001 - 13:27:25 CDT