(original) (raw)

On Tue, Mar 11, 2014 at 2:59 PM, R. David Murray <rdmurray@bitdance.com> wrote:

On Tue, 11 Mar 2014 19:57:36 +0100, Georg Brandl <g.brandl@gmx.net> wrote:

> Am 11.03.2014 15:54, schrieb Guido van Rossum:

> > I'm not sure I agree completely with this lax attitude about the contents of the

> > docs, and especially the What's New parts of it (both Misc/NEWS and

> > Doc/whatsnew/3.4.rst).

>

> I don't think anyone here suggested not to update the whatsnew document.

>

> > I find it very useful to have these pinpoint *exactly*

> > what made it into the tarball or zipfile or whatever other form I happen to find

> > the release -- you don't always have the full hg logs lying around, nor do you

> > always know from which exact revision or tag a tree was built.

As far as NEWS goes, I fixed some issue callouts so they'll be links in
the online version, I deleted a couple redundant entries, I fixed wording
here and there, and I added...three?...entries that were missing but I
found the commits from the versionadded or versionchanged doc updates
they contained that Serhiy found. �I'm sure there are other missing NEWS
entries that weren't caught, so wanting to know \*exactly\* what is in the
release is a lost cause unless you look at the commit log :) Especially
since the revision that contains the commit related to those added
news entries does \*not\* contain the news entry I added, so if you had
a tarball built from that revision you wouldn't have that news entry...

OK, understood. The thing is that I like the granularity of Misc/NEWS -- it doesn't cover everything, but it covers pretty much everything you might care about. The changelog is way too verbose.

--David

PS: Also, sad to say I picked up the What's New task late in the 3.3

release cycle, and even with doing additional work *after* final I did

not finish. �So that document may be missing stuff...and in any case,

What's New never promises to include *everything*. �I have been more

completest in 3.4 than Raymond (intentionally) was for 3.2, but it still

doesn't have *every* enhancement.

I think that's a feature. What's New has always been an opinionated document -- it goes from most to least important, and has a structure that makes "skimming" particularly efficient.

--
--Guido van Rossum (python.org/\~guido)