"what's new" document

[Ben Finney]

Martin Pool <mbp at canonical.com> writes:

> [A “What's New in version FOO” document provides] a readable summary
> both for users and other participants of what's changed […]. It is
> complementary to NEWS and I think we should keep both. (Obviously
> there is some redundancy but I think it's worth while.)

Definitely worthwhile. As a user of Bazaar this kind of document will be
much appreciated.

> So when you change something notable, please consider adding it to
> this document. Then before actually doing the release we will check
> and edit it. "Notable" is fuzzy but it could mean a compatibility
> change, a new feature, a performance improvement.

The threshold might be “how would you describe the changes to an
existing user of $FOO_VERSION−1, if you knew you only had thirty seconds
before they lose interest” or some similar measure of notability.

Robert Collins <robertc at robertcollins.net> writes:

> Firstly, this is harder on users. They have to chase points - a change
> in 2.3 which started in 2.0 will require three additional lookups -
> assuming only one point release at each point.

I don't understand what this means. What is a “point” in your
terminology? How are points different from changes?

I would only expect the “What's New” document to describe changes since
the previous released “What's New” document. If I'm a user upgrading
from a version that's out of date by several versions, I read the
“What's New” document for each version released since then.

-- 
 \           “Value your freedom or you will lose it, teaches history. |
  `\     “Don't bother us with politics,” respond those who don't want |
_o__)                               to learn.” —Richard Stallman, 2002 |
Ben Finney