[Zope-dev] Extend specification of how to maintain the changelog

[Christian Theune]

Hi,

This post refers to Philipp's guide for `Maintaining software in the Zope
software repository` [1].

I noticed that I kept getting confused about maintaining CHANGES.txt entries
when merging bug fixes around, looked around a bit and thought I'd share my
findings.

First, I think we have a terminology issue as the standard form of 'ChangeLog'
refers to individual changes, pretty much as what is recorded by subversion's
log. (See [2] and [3].)

What I understand from the Wikipedia entries for Changelog [4] and Release
notes [5] is that what we record in the CHANGES.txt files is closer to release
notes than a changelog. This is just an observation -- I'm happy with the
actual content of what we use to put into the CHANGES.txt file.

The core problem in maintenance is that I wasn't sure how to record bug fixes
that are applied over multiple branches (trunk and maybe one or two
maintenance branches). I discussed this a bit and found the following way that
looks reasonable:

- The CHANGES.txt is mainainted for each release series in their branch
  (obviously).

- The first section marks the next released (as specified in [1]).

- A change on a branch is recorded in the next unreleased section. (Merges of
  the same fix over multiple branches are not recorded in different places on
  the other branches.)

This results in the following properties for the CHANGES.txt:

- The trunk will contain sections for feature releases (e.g. 1.0, 1.1, ..) but
  not bugfix releases (e.g. 1.0.2).

- Bug fixes will appear once in the feature release of the trunk (e.g. 1.1)
  and once in each individual dot release of the various maintenance branches
  that it went into (e.g. 1.0.y)

- There is not individual "large" CHANGES.txt that appears to be a simple
  concatenation of the various changes on branches because we respect the
  tree-ness of maintenance branches.

I find that Philipp's guide could be extended/clarified a bit more about this.

Comments, suggestions, etc. welcome.

Christian

[1] http://svn.zope.org/*checkout*/Sandbox/philikon/foundation/maintaining-software.txt
[2] http://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs
[3] http://www.gnu.org/software/guile/changelogs/guile-changelogs_toc.html
[4] http://en.wikipedia.org/wiki/Changelog
[5] http://en.wikipedia.org/wiki/Release_notes


-- 
Christian Theune · ct at gocept.com
gocept gmbh & co. kg · forsterstraße 29 · 06112 halle (saale) · germany
http://gocept.com · tel +49 345 1229889 7 · fax +49 345 1229889 1
Zope and Plone consulting and development