[Zope3-dev] the maintenance of change logs

[Martijn Faassen]

Jim Fulton wrote:
> 
> On Sep 22, 2006, at 11:47 AM, Martijn Faassen wrote:

>> I am about to do a new egg release of zc.catalog and will be putting 
>> out other eggs as well (to the cheeseshop as we now have our own 
>> category there).
>>
>> I notice in the SVN that there have been quite a few changes to 
>> zc.catalog. We do not have any CHANGES.txt or such, so it's very hard 
>> for me to determine what in fact changed without digging through SVN 
>> commit messages and such.
>>
>> So, I propose we start maintaining CHANGES.txt in packages, and mark 
>> changes there when we make them.
> 
> I'd rather see this in projects, not packages.  So this would be in the 
> root of an SVN project alongside of setup.py.
> Maybe this is what you meant.

Yes, sorry for being unclear, that is what I meant.

[snip]
> See what I've been doing for zc.buildout:
> 
>   http://svn.zope.org/zc.buildout/trunk/CHANGES.txt?view=auto

I took a look at it after I wrote this post.

> Some things to note:
> 
> I knit all of the .txt files, including documentation-oriented doctest 
> files together in the distutils long description.  This causes the pypi 
> page to be pretty informative:
> 
>   http://www.python.org/pypi/zc.buildout

I looked into doing this for zc.catalog as well, but in the end decided 
not to. zc.catalog contains quite a few doctests and the knitting would 
be quite involved, so I deferred the work.

While I'm happy with the way this works now as it's agile, I am also 
hoping that eventually we can move away from the cheeseshop as the prime 
documentation site of a project; it's not ideally suited for that.

I hope we can move to a pattern where projects gain a homepage somewhere 
on zope.org, including doctests and some other information, and the 
cheeseshop is used for everything else (pointing to the homepage on 
zope.org with the 'url' field in setup.py).

[snip]
> I find putting dates on releases to be a bother.  If it's a bother for 
> me, it's probably a bother for others.  Is it really worth it?

I really appreciate seeing release dates myself. I already found myself 
wondering the other day whether a release of zc.buildout was new or 
whether I'd seen it again. Release dates help there. It is also helpful 
to track a project's release history later.

If the cheeseshop had release dates for files somewhere visible then I'd 
be okay with leaving them off.

> I've done a bad job of tagging releases,  I need to get better about that.

Yes, as not tagging removes one more way to determine the release date. :)

> Finally, I'm experimenting with using launchpad for bugs:
> 
>   https://launchpad.net/products/zc.buildout/+bugs
> 
> and feature requests:
> 
>   https://features.launchpad.net/products/zc.buildout/
> 
> So far this is working OK. I haven't really stressed it. Launchpad makes 
> this very easy to set up and I don't think they are allergic to having 
> us create lots of projects.

I intend to take a look at this later.

Anyway, we need to start writing this stuff down in an easily found 
place. Like zope.org...

Regards,

Martijn