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

Subject: Re: [Boost-docs] A better way to do release notes?
From: Edward Diener (eldiener_at_[hidden])
Date: 2011-02-14 21:26:14

On 2/14/2011 12:38 PM, Beman Dawes 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?

 From a design point of view, especially as Boost possibly wants to go 
from a monolithic structure/distribution to individual libraries ( which 
I also believe is the right direction ), I agree with you that the 
release notes for a library should be part of that library's structure. 
I have not seen any Boost doc about release notes format for a library. 
Does that exist ?

For my sandbox libraries I started out having a history text file which 
had the information about each release, but then I decided that was 
redundant and folded the history into a History section in my quickbook 
documentation. But any established Boost way for dealing with history of 
any library leading to release notes would be great, and I applaud your 
idea that this should be done in a regular manner so that the Boost 
release notes can pick up that information as necessary.

As an added thought, if libraries ever go the way of being released 
separately from a Boost monolithic release, there needs to be some way 
of syncing a library's idea of "version number" with a Boost release's 
idea of "version number" and this should be eventually be part of plans 
for release notes and library history.