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