Bazaar 2.1.0 has gone gold

[Andrew Bennetts]

Ian Clatworthy wrote:
> John Arbash Meinel wrote:
> 
> > It is my summary blurb for the 2.1 release. If you don't want to include
> > the ~100 bugfixes, then I don't know that there is a lot more to say.
> > You certainly can go into details about the individual features, but
> > your whole point was that you wanted a summary of the primary
> > differences between 2.1.0 and 2.0(.4).
> 
> I thought your summary was a good start. It's hard getting the balance
> right between a paragraph and 20 pages. :-)
> 
> I've taken a crack at expanding what you wrote. See attached. It needs a
> few more links but I'm otherwise happy with it. If this looks OK, I'll
> submit a MP adding this as a section into NEWS.
> 
> First off though, I'd like some feedback from potential readers of
> this material. If your team was going to upgrade to 2.1, does this
> document meet your needs wrt understanding What's New?

I really like this text, but I'm not sure if it's a good fit for the
NEWS file.

Perhaps we should do it the way Python does it?

Python has a NEWS file (which they keep in Misc/NEWS), which looks quite
a lot like our NEWS file: a list of terse bullet points describing every
non-trivial change, categorised into a few major sections.  Each bullet
usually has a bug number, and often credits the contributor by name.
This is very very similar to our NEWS file.  (So similar that I'm going
to use it as a use-case for guiding enhancements to the news_merge
plugin: if I can make it configurable enough for both ours and Python's,
then I think it'll be in good shape.)

However, as I'm sure you'd agree, most end users are better served by
actual paragraphs of text telling them about the highlights, ideally
with examples and even links to find out more.  Python has this too:
each release has a “What's New in Python X.Y” document.

I think the same model would suit us too.  NEWS files are great for
people that really want to find out if bug 1234 was fixed in this
release (that includes packagers and also users that have a pet bug).
A “What's New” page is great for most users that just want to know what
the interesting changes from X.Y to X.Z were — which is probably most
users.  But I think both audiences are important.

An advantage to keeping these as separate docs is that point releases of
a stable release can refine the “What's New” doc easily.  And I think it
the audience for a “What's New” page would be better served with the
clutter of NEWS's bullets kept out of it (although providing a link to
NEWS would make great sense, of course).

-Andrew.