Thoughts on Release Notes

[Martin Pool]

On 6/15/07, John Arbash Meinel <john at arbash-meinel.com> wrote:
> It would be nice to see a summary of NEWS, which coalesces the different
> changes, etc.
>
> Right now, I don't know that it is worth the effort, (I'd rather spend the hour
>  in bug triage/fixing a bug).
>
> But I think that as we approach a 1.0 it might make more sense. Certainly NEWS
> is more like our ChangeLog (though 'bzr log --short' makes a pretty good change
> log, too).
>
> It is always possible to have things in the (inverse?) pyramid style. Where you
> give a short summary, and then expand, and then expand, etc. So that however
> far someone reads, they get a little bit more detail about what is going on.
> And if we have someone who is good at that (Ian?) then by all means we should
> do so. I guessing that for me to write a good writeup would take a couple of
> hours. And whether that would be better spent elsewhere is a point of discussion.

An hour is probably too much, but a couple of minutes just giving the
main themes of the release or improvements, or things that people
particularly ought to do or watch out for when they upgrade would be
good.  I tried to prepend that to my announcement mails but adding it
in to NEWS is probably better.  I suppose realistically even just
doing a paragraph or two and making sure you've got it right would
take 15-30 minutes.

-- 
Martin