user-oriented news

[Martin Pool]

I would just like to remind people about the style for news entries:
specifically, they should tell a user of bzr (or a plugin developer),
what changed and what to expect.

If we fix a bug, it's better to describe the external behaviour of the
bug, rather than what we changed to fix it.  Then people will know (or
have a chance to know) whether the problem they were experiencing was
actually the problem we fixed.  Quoting the error you used to get
before we fixed it is a good idea. Mentioning the classes we changed
is probably not so helpful.

(Commit messages, intended for people actually working on bzr, are
different, and it's much more appropriate to describe how you fixed
something.)

There are supposed to be two different sections in news per release,
one "compatibility breaks" and the other "api changes".  The first is
supposed to be about things that could cause incompatibility for users
of Bazaar.  If we deprecate or remove a command or option, break
network compatibility, add a new default format, or change a default
behaviour that should go in here.  It should be a short list of things
that might require people to change their shell scripts or muscle
memory.  At the moment for 2.3b1 it has a bunch of things that to me
seem quite internal.  I don't know if this is due to misunderstanding
of the heading or a slip of merging fingers.

The api changes are things that might require changes in code that
uses bzrlib, and typically there will be somewhat more of them.

There is also an 'internals' section; the line between what should be
mentioned here and what's just in the commit messages is a bit grey.
Perhaps things that affect a lot of code or that someone catching up
on development would find notable.  Similarly 'testing'.

Separately, I think spiv is going to propose a split-up of the news
into one per series.

-- 
Martin