Thoughts on Release Notes

[Ian Clatworthy]

casret wrote:

> Tangentially, I think there is a need for release notes.  It's all in the
> NEWS file, but I think the arrangement needs to be tweaked.  I think that
> all the changes from the release candidates should be coelesced, since most
> end users don't see the release candidates.  I also think breaking up first
> by sections (UPGRADING, IMPROVEMENTS, INTERNALS, BUGFIXES) and then in each
> of the sections breaking down by release info would be helpful.  So someone
> upgrading from e.g.: 0.11 to 0.16 knows exactly how to do it or what to
> expect.  It would also be great to have that or maybe just the top part of
> the NEWS file linked to the release announcement in the wiki, so I wouldn't
> have to pull down the tarball (which I wouldn't use for upgrading anyway)
> just to see the changes.

I'd personally like to see Release Notes as well. They can take a bit of
time to do well but I think that investment is often worth it for final
releases.

NEWS is a good starting point and arguably sufficient for Release
Candidates. But I feel it falls a little short vs good Release Notes for
several reasons:

1. It is built up over time so the ordering and presentation of
   information is a little hap-hazard instead of being user centric.
2. Some things get missed.
3. When taken as a whole from release to release, the information is
   potentially inaccurate.

Performance figures are a good example of the last case. As a developer,
I might well see n% improvement so I state that in NEWS. But other fixes
or improvements can eat into those gains or amplify them, depending on
how various changes interact. It's not a big deal but it does highlight
the fact that end users and developers have different needs and perceive
products in different ways.

Upgrade Notes are a slightly different challenge again. I think it is
worth having those separate from but referenced from the Release Notes.

The flip side to all the above is that we're still pre 1.0 and releasing
new software monthly. I'm happy to see most our energy going into better
software right now instead of gold plating the doc. But that balance
will need adjusting IMO as the user base of Bazaar goes from early
adopters to a larger crowd.

Ian C.