[python-committers] what's going on with Misc/NEWS?

[R. David Murray]

On Fri, 24 May 2013 15:16:24 -0600, "Gregory P. Smith" <greg at krypto.org> wrote:
> On May 24, 2013 2:55 PM, "Antoine Pitrou" <solipsis at pitrou.net> wrote:
> >
> > Le vendredi 24 mai 2013 à 16:22 -0400, Brett Cannon a écrit :
> > > >
> > > > I don't understand why it's painful to backport. Can you explain?
> > >
> > > If I make a very minor fix to the docs I have to:
> > >
> > > # In a 3.3 checkout
> > > Fix docs
> > > Compile docs
> > > Add Misc/NEWS entry
> > > hg ci -m "repeat what I just said in Misc/NEWS"
> > > hg push
> > > cd ../default
> > > hg merge 3.3
> > > Fix/revert Misc/NEWS (at least)
> > > Compile docs (if fix is needed)
> > > hg ci
> > > hg push
> >
> > I honestly don't understand why you would mention doc fixes (even major
> > ones) in Misc/NEWS. It's not a useful piece of information to have
> > there. People want to know about bug fixes because they are affected by
> > bugs, but doc fixes??
> 
> I think you misunderstood what he meant. Misc/NEWS is documentation. I
> believe he meant he won't fix typos in NEWS due to the make pain involved.

No, he really meant he created a news entry for a doc change.  For a
reasonable reason, in the example he gave :)

But you certainly don't need a news entry for typos, or most other
doc changes, IMO.

> I'm the same way. I want nothing to do with news when making my changes
> because it ALWAYS gets in the way for any change not being done on
> head/default/tip only. If anything I prefer to leave news entries out of
> the commit they are related to to avoid news merges going wrong from
> messing up the real change. Hopefully I remember to write a news entry for
> it after the fact.

In the subversion days almost every merge I did had a NEWS conflict.
With hg, I only get a merge conflict if the most recent change to NEWS
is a 3.3-only entry.  So, maybe half the time.  (I suppose if people
are really sticking entries in randomly I might start seeing more
conflicts...)

I have no objection to the process being improved if someone is willing
to do the scripting to improve it.  I personally would prefer not to
simply have the files have different names, meaning I'd have to copy the
news entry all the time instead of half the time.  But my objection is
only about -0.25, so if more people prefer making the file names different
in the absence of a better scripted solution, I'll live with it :)
I just hope we don't start losing NEWS entries as as result.

Oh, and my news entries are almost never the same as my commit one-lines,
partly because I keep the commit line to *one* line, whereas the NEWS
entry is typically two to three.  Keeping the first commit line to one
line makes reading the log easier, IMO; but I suppose since not everybody
does that it's really just a quirk :)

But even without that the messages would different.  As someone else
mentioned, I feel that the audiences are different...and in the commit
message I assume that you are seeing the list of changed files as well,
to give you context for the commit message that isn't present in the
NEWS entry.

--David