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

[Brett Cannon]

On Fri, May 24, 2013 at 2:27 PM, Antoine Pitrou <solipsis at pitrou.net> wrote:
> Le vendredi 24 mai 2013 à 14:23 -0400, Brett Cannon a écrit :
>> > You'll have to copy stuff by hand, though, if you don't want to rely on the
>> > merge machinery. So we have two possible file layouts:
>> >
>> > * (current) a single Misc/NEWS is merged from branch to branch. Pro: hg merge
>> > copies the text for you. Con: hg merge sometimes screws up and you have to
>> > clean up a large conflict.
>>
>> But hg won't let you simply revert;
>
> hg rev -r <branch name> Misc/NEWS

I'll add that to the devguide if it works for me next time.

>
>> > * a dedicated Misc/NEWS-x.y per major version. Pro: no merge conflicts ever.
>> > Con: you have to copy the message by hand when merging a bug fix to the upper
>> > branch. Con: it's easy to forget to copy the message (hg won't yell if you
>> > don't
>> > do it), so people *will* forget (and it's annoying grunt work for those who
>> > notice it).
>>
>> So the question becomes do we really need to copy every entry? Beyond
>> simply being redundant, it's annoying when doing merges because of the
>> constant conflicts. I would argue that in bugfix releases we could say
>> in the issue whether it stops there or propagates into the next
>> feature release (e.g. [regression] or [bugfix]). Then it becomes habit
>> to always specify that (and maybe even have a Mercurial extension that
>> detects when neither is specified and throws a fit).
>
> Then Misc/NEWS* become harder to read for third parties, since reading
> Misc/NEWS-3.4 won't tell you everything that happened in 3.4.

This is when we could have a script that just pulled from both 3.3 and
3.4 NEWS files and makes a single one.

>
>> Either way the status quo makes me not want to fix small doc typos
>> like a missing parenthesis since this is enough of a hassle to not
>> make it worth it.
>
> Do you mean Mics/NEWS doc typos?

No I mean typos in the docs. For instance, I found a missing
parenthesis in the docs for some module, but backporting it is enough
of a pain that I don't want to bother. The only reason I did this one
for sys is because it clarified semantics.

>
>> > The major con with the current scheme *might* be solved by a dedicated hg
>> > extension, but someone needs to have enough free time and passion to try and
>> > write it :-)
>>
>> Wouldn't an extension that does the copying be easier than resolving
>> the conflict?
>
> Sure, it would be. Like Nick said: if you are motivated enough to write
> the extension... :-)

We'll see.