[Zope3-dev] Proposals vs. developer docs [was: Reducing the Amount of ZCML Directives ready for review]

Philipp von Weitershausen philipp at weitershausen.de
Mon Mar 20 06:01:59 EST 2006


Martijn Faassen wrote:
> Philipp von Weitershausen wrote:
> > Philipp von Weitershausen wrote:
> >
> >>If no one objects to the branch as it is, I will merge it on the weekend.
> >
> >
> > Done now.
>
> Did you manage to make a start on a developer changes document for Zope 3.2?

Not yet. I've thought about this some more. I think that you're right about the
developer visibility of changes. I also think that doubling information in the
wiki and in the source (where it will likely rot if it's not a doctest) isn't
ideal.

In fact, I very much like how two other Zope-related projects handle this:
Python with its PEPs and Plone with its PLIPs. When they describe the feature
changelog of a major version, they can just point to the numbers of the PEPs
and PLIPs and voila, you have a very visible list of what happened in a
particular release. The same is also true for the feature roadmap (IOW,
upcoming changes), as http://plone.org/products/plone/roadmap nicely
demonstrates.

We claim to have a formal development process because it's proposal driven.
Let's go all the way and number proposals like PEPs and PLIPs. They usually
already have meaningful names, so changelogs or roadmaps can look like this:

  * Implemented proposal 234: Refactor traversal to lead to Rome

  * Implemented proposal 242: Speed up ZCML by 1000%

  * Fixed collector #3241: All traversal is leading to Florence, not Rome

  * ...

  where the text after the colon is the name of the proposal or the collector
issue.

I find changelogs and roadmaps like these very easy to read. It also makes it
very easy to find the information you're looking for. Just google for
{PEP|PLIP|...} # so-and-so. Any deprecation messages associated with certain
proposals could also refer to the proposal number and name.

Of course, ideally a generated HTML version of the changelog would also contain
links to the respective proposals and collector issues. This is easily doable
when the changes docs follow a certain structure. Trac, for example, treats
#234 as ticket numbers, r2342 or [2342] as revision numbers, etc. We could
follow a similar convention.


We should also require a common structure in proposals and provide a reST
template for them, just like they do with PEPs (and possibly PLIPs?). Most
recent proposals already follow a certain structure (Current Situation,
Problem, Goal, Proposal, Risks, Implementation Status). I think this would
work well for a formal proposal structure


By the way, I also like how PEPs <20 contain some common style guides and
Python zen. I think some of the wiki pages that explain Zope 3 coding style
guidelines etc. could also be "converted" into proposals, IOW, assigned
proposal numbers.

Philipp


----------------------------------------------------------------
This message was sent using IMP, the Internet Messaging Program.


More information about the Zope3-dev mailing list