Re: [Boost-docs] A better way to do release notes?

Subject: Re: [Boost-docs] A better way to do release notes?
From: Stuart Dootson (stuart.dootson_at_[hidden])
Date: 2011-02-15 09:50:19

On 14 February 2011 17:38, Beman Dawes <bdawes_at_[hidden]> wrote:

> I've got several concerns about the current release notes mechanism:
> * The file where I supply my library's release notes markup is not
> part of my library, so it is a pain to keep up to date, and not within
> my library's version control history.
> * While the global Boost release notes page is nice for finding out
> what happened to each library in a given update, it isn't any good for
> seeing what has happened to my library release by release. I'd really
> like that to be in my libs/libname/doc subdirectory.
> Perhaps libraries could have a local release notes markup file in
> their libs/libname/doc subdirectory:
> * That markup file could have a separate section for each release.
> * The global release notes generation process could automatically pull
> out the section for the current release.
> * There could be a separate Jamfile in my library's libs/libname/doc
> subdirectory that generates my library's
> libs/libname/doc/release_notes.html file, covering all past releases.
> * This be done only for libraries that want to go that route, so
> nothing changes for libraries that don't want to use this mechanism.
> Is that possible? Practical? Thoughts?
> --Beman
Beman - I've done something kind of similar to that with a product here at
work, which consists of a couple of executables and a host of DLLs. I use a
standard XML schema to define, in separate sections, 1) the set of
executable/DLL versions that make up a baselines release, and 2) the set of
changes worked in any executable/DLL version. I then have XSLT files to
produce separate HTML files for 1) a delivery manifest, 2) the aggregated
changes for a release, and 3) a change history for all releases.

While I haven't got separate XML files for each executable/DLL (I maintain
them all!), this would be pretty simple to do using XInclude...

It seems to work pretty well, well enough that we've re-used the idea on a
few other of the larger projects we've worked on here. The advantage of
using XML, I've found, is that I do have a defined XML Schema, so syntactic
correctness is checked. And I'm sure some level of semantic checking (that
no unknown versions are referenced, for example) could easily be added.

Stuart Dootson

This archive was generated by hypermail 2.1.7 : 2017-11-11 08:50:41 UTC