[Zope3-dev] the maintenance of change logs
Jim Fulton
jim at zope.com
Fri Sep 22 12:06:51 EDT 2006
On Sep 22, 2006, at 11:47 AM, Martijn Faassen wrote:
> Hi there,
>
> 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.
> The format I propose is in restructured text, like so:
>
> ==================
> zc.catalog changes
> ==================
>
> 0.2 (2006-11-22)
> ================
>
> Features added
> --------------
>
> * zc.catalog can now do even more wonderful things.
>
> Bugs fixed
> ----------
>
> * fixed a bug where zc.catalog wasn't doing the right thing.
>
> What do you think?
See what I've been doing for zc.buildout:
http://svn.zope.org/zc.buildout/trunk/CHANGES.txt?view=auto
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
The knitting happens in setup.py,
http://svn.zope.org/zc.buildout/trunk/setup.py?rev=70198&view=auto
While this is still pretty experimental, I'm pretty happy with it.
To make this work requires coordinating headings across all of the
text files. which lead to my use of *s in the root text files.
Also, for individual packages, I think we can be a little more
lightweight. For example, I think we can avoid separating features
and bugs.
I also think it's nice to provide some information about status and
plans.
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've done a bad job of tagging releases, I need to get better about
that.
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.
Jim
--
Jim Fulton mailto:jim at zope.com Python Powered!
CTO (540) 361-1714 http://www.python.org
Zope Corporation http://www.zope.com http://www.zope.org
More information about the Zope3-dev
mailing list