user-oriented news

[Martin Pool]

A couple of other things from working through this:

I see a lot of the misordered messages came in during the 2.1/2.2
release; I don't know if that was due to a mechanical merge failure or
user error; please be careful.

Please put things that are only relevant to testing into the testing section.

I am quite skeptical about duplicating news entries when we merge up
from the release branch to the stable branch.  Aside from anything
else, it bloats the file and if we later need to fix things up there
are redundant copies.

The general model is users can read through the file as far as they
want.  I think we should add "improvements" before "bug fixes" because
the former may be interesting to more users.

I've changed "Compatibility Breaks" to "External Compatibility
Breaks", to make it more clear.  I'm thinking of adding some comments
in each section to help users and us understand what goes there.

https://code.edge.launchpad.net/~mbp/bzr/doc/+merge/38092

On 11 October 2010 14:50, Robert Collins <robert.collins at canonical.com> wrote:
> On Mon, Oct 11, 2010 at 4:35 PM, Martin Pool <mbp at canonical.com> wrote:
>> 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.
>
> While I take your point about communicating effectively with our
> users, this isn't really a dichotomy - we can describe both the
> external behaviour and what we changed; NEWS is rather more accessible
> and pithy for developers and plugin developers catching up on things.

That's true.  It's not that I want to get rid of the discussion of the
internals, but I want to make sure there is a discussion of the
external impact.

For instance

* Prevent ``CHKMap.apply_delta`` from generating non-canonical CHK maps.

is not going to mean anything to most users, but

* Prevent ``CHKMap.apply_delta`` from generating non-canonical CHK maps,
  which can result in "missing referenced chk root keys" errors when
  fetching from repositories with affected revisions.

tells them that if they never saw that error, this is irrelevant, and
if they did see it, it may now be fixed.

* Raise ValueError instead of a string exception.

is not a good message because it has no scope.  Did we do that
absolutely everywhere, or just in one place?

* Reduce peak memory by one copy of compressed text.

sounds excellent, but again has no scope.  For all operations?  For
things I never run?

* Reduce peak memory by one copy of compressed text when writing to pack
  repositories.

which I added based on the bug, and which gives you a better idea how
interesting it is.

-- 
Martin