[Zope3-dev] Re: RFC: Guide for maintaining software in the Zope repository

[Philipp von Weitershausen]

Tres, thanks for the comments!

On 25 Aug 2007, at 18:08 , Tres Seaver wrote:
> Philipp von Weitershausen wrote:
>> We have 100+ packages that make up what used to be distributed as
>> "Zope3". We have numerous more packages in svn.zope.org. Most of them
>> are developed, released and distributed individually. We like to  
>> think
>> this is a good thing (I certainly do). But currently we have a bit  
>> of a
>> chaos [2]. It's not bad, but I fear without some guidance, it'll  
>> get worse.
>>
>> Christian Theune recently wrote a document [1] in which he  
>> outlined how
>> we should get to a development process and what topics it should  
>> touch.
>>   This document is very hands-on and describes actions that should be
>> taken to reach these goals. I've taken the liberty to jump ahead and
>> write down some current practices:
>>
>> http://svn.zope.org/*checkout*/Sandbox/philikon/foundation/ 
>> maintaining-software.txt
>
> Thanks for drafting this document. A couple of comments (mostly  
> niggles).
>
>  - At then end of the last summary bullet under "Repository layout",
>    you say, "Release tags shouldn't be committed to."  I would say
>    that is true *after* the release is announced.  Sometimes it may
>    be more convenient to modify the tagged code during the process of
>    making the release (see below).
>
>  - The changelog should include dates for each release, formatted
>    consistently (ISO short form is likely best, as it is unambiguous).

Two very good points. I fixed those in the document.

>  - Under "Releasing Software", you specify what is to me a  
> controversial
>    rule:  "Increase the version number (in ``setup.py`` and elsewhere)
>    on the trunk or the release branch to the *next* release."  While I
>    realize that many projects are doing this, I don't like it:  I  
> prefer
>    that the trunk changelog contain an "unreleased" section for  
> features
>    / changes not tracked on the current release branch.

The point about the changelog is good. Whoever is making the release  
should create a new section (marked "unreleased") in the changelog so  
that committers won't add their entries in an already released  
version's section. I've added that to the document as well (incl. an  
example).

>    In particular, I don't want to make it easy for somebody with a  
> trunk
>    or branch checkout to create a pseudo-release egg.  In this case,
>    "speed kills", because sloppy release making punishes everybody
>    downstream.
>
>    I would therefore advocate keeping the 'version' tag on the  
> trunk to
>    something containing 'trunk' or 'unreleased'.  Release branches
>    should contain 'branch' in their version, except immediately before
>    copying to a release tag.  As an alternative (see above), copy the
>    release tag and then change the version there.

This is not a bad suggestion. As I was explaining in my original  
email, I was mostly capturing our best practices so far. That doesn't  
mean the guide can't shape things for the better, but we should reach  
a consensus first. At least the guide is spurring awareness and  
discussion of these practices, which was part of the idea.

I would suggest a mixture of our current practices and your  
suggestion: A release branch or the trunk's version statement in  
setup.py should contain both the version of the next anticipated  
release. As a marker for the fact that we're dealing with a  
development version, I suggest using the 'dev' marker that seems to  
be quite common around.

So, on a branch or the trunk, setup.py should look like this:

   setup(version='1.1dev',
         ...

whereas on a release tag, it should always look like this:

   setup(version='1.0',
         ...