user-oriented news

[John Arbash Meinel]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1


...

> 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.

I don't think I've ever heard this advice before. Especially the
"quoting the error you get" part.


> 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'.
> 


These were also never clearly defined to me. I always felt that Internal
changes were a bit unclear and just put everything into Compatibility.
Certainly that has always been the advice on Merge Proposals ("that
needs a section in Compatibility", never "that needs a section in
Internals")

I think I only used Internals for *new* apis. Stuff that people might
want to use, but not stuff that might 'break'.

Maybe it was covered in HACKING, I'll certainly admit that I don't
really read that document, vs just using experience-to-date from being
part of the project.


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

I think that's great for a whole lot of reasons.

John
=:->
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAkyzFncACgkQJdeBCYSNAANdkwCfVhXp18QS8oVIArvocq/E0GN1
hXUAoL6gRHAeroDtDdUB78AcqvSUfny8
=2NTk
-----END PGP SIGNATURE-----