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).
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.
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).
Regards, Nick.
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.
On 01/29/2013 01:55 PM, Dan Callaghan wrote:
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.
If we make a design doc a requirement to get big changes through code review, they'll get written :)
I think integrating them into the main Beaker website will also help make it feel more worthwhile to write them, since they'll be more readily available as reference documents in the future.
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.
Fair point - since they'll be individually numbered, I guess it doesn't make sense for them to also be versioned. To make it easy to create the index page listing them all, I think Sphinx will be a better fit than Markdown, though.
Publishing direct to the website also makes it easy to meet the goal of providing advance notice to users of upcoming changes, which wouldn't work if the design proposals were in the main repo.
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.
The way the PEP process works, the PEP and the reference implementation almost always end up co-evolving. (e.g. the main PEP I am currently working is PEP 432, which redesigns the interpreter initialization process. I wrote enough of the PEP to figure out how I *wanted* the new design to work, and am now working on the implementation to discover what I missed in the original design).
I do like the idea of using the Gerrit review process on the code implementing the design as the tool for approval, though.
My one concern with changing the name is how we deal with them getting out of date. With PEPs, the language reference is always taken as authoritative once the PEP is incorporated - the PEP itself is almost never touched again once it goes to Final. So the PEPs *do* get out of date over time, but that's OK because they've been superseded by the official docs by that point.
With a *living* design document, you *do* want that to live in the main Beaker repo, since you want it to be accurate for the current version, but it's free to change between versions.
We don't have an "Architectural Guide" yet, but I do think we need one and that would be a good place for living "Beaker Design Documents" that dive into the implementation of particular details to live. Any feature big enough to deserve a Design Proposal would then either create a new Design Document or update an existing one.
Cheers, Nick.
beaker-devel@lists.fedorahosted.org
-
Dan Callaghan -
Nick Coghlan