Excerpts from Nick Coghlan's message of 2013-01-29 13:42:26 +1000:
One thing I noticed when starting work on Beaker is that a lot of the
design rationale for major architectural decisions is hidden in email
archives (including Red Hat internal ones), Bugzilla entries and code
reviews on Gerrit.
To make it easier for new developers to understand past architectural
changes/additions, to help users to understand changes coming in future
releases, and to help us be confident that our proposed designs are
solid, I'm suggesting we adopt a "Beaker Design Proposal" process for
major changes (such as the scheduler updates I'm working on, the
upcoming integrated dashboard, the "system pools" concept, self-service
user groups and group jobs).
I am unashamedly stealing this concept from Python's PEP process,
because I like it and I think it works pretty well in ensuring that the
*rationale* for a design is captured in addition to forcing us to think
a bit more about the design itself before diving into code. As with
Python, only major changes would need to be written up as a design
proposal - bug fixes and smaller features would be handled through
Bugzilla as usual. In recent times, the integration with oVirt Engine in
0.10 is probably the only change big enough to qualify (although the
Supported Query idea might have been worth writing up as well).
+1 to this idea generally.
In the Eng Ops days we were supposed to do a "Software Design Document"
before every major enhancement, which seems like basically the same
thing, though in reality we never got around to writing them.
In terms of mechanics, I'd largely follow the Python model for
numbering: reserve BDP 1 for the meta-proposal describing the process,
BDP 2-99 for any other meta-proposals we come up with, and start the
actual design proposals at BDP 100.
Publication would be via Sphinx on
beaker-project.org: the design
proposals would just live in another docs directory alongside the
existing User and Admin guides.
These seem like "meta-documentation" so I think they should be outside
beaker's git. Not sure if that's what you intended.
BDP approval rights would rest with the Beaker Development Lead (i.e.
currently me) or their delegate (similar to the way PEP approval rights
ultimately rest with Guido van Rossum as Python's BDFL, but one of the
other senior core developers may take on the role of BDFL-delegate for a
particular PEP).
Not sure if we need such a heavyweight "approval" process, ultimately if
there is code and it gets merged then it is "approved". It may be more
realistic to look on these as documentation rather than proposals (and
perhaps even just call them Beaker Design Documents?), acknowledging
that we won't always get around to writing one before we write the code.
--
Dan Callaghan <dcallagh(a)redhat.com>
Software Engineer, Infrastructure Engineering and Development
Red Hat, Inc.