[python-committers] what's going on with Misc/NEWS? (original) (raw)

R. David Murray rdmurray at bitdance.com
Sat May 25 05:00:00 CEST 2013

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

More information about the python-committers mailing list