[python-committers] what's going on with Misc/NEWS?
I was trying to do a simple merge of a doc change between 3.3 and default and the usual Misc/NEWS conflict came up. But when I looked at the diff it was massive! Turns out that Misc/NEWS in default goes from 3.3.1rc1 to 3.4.0a1 (http://hg.python.org/cpython/file/24ffb0148729/Misc/NEWS) while Misc/NEWS in 3.3 goes properly through all versions between 3.3.1rc1 to 3.3.3rc1 (http://hg.python.org/cpython/file/3c4a5dc29417/Misc/NEWS). I have to get to work so I don't have time to fix this, but if someone does have the time to unwind this mix-up that has accumulated that would be great. And maybe it's finally time to bite the bullet and come up with some way to automatically generate Misc/NEWS from commit messages. ___ python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
Re: [python-committers] what's going on with Misc/NEWS?
On Fri, May 24, 2013 at 10:24 PM, Brett Cannon wrote: > I was trying to do a simple merge of a doc change between 3.3 and > default and the usual Misc/NEWS conflict came up. But when I looked at > the diff it was massive! Turns out that Misc/NEWS in default goes from > 3.3.1rc1 to 3.4.0a1 > (http://hg.python.org/cpython/file/24ffb0148729/Misc/NEWS) while > Misc/NEWS in 3.3 goes properly through all versions between 3.3.1rc1 > to 3.3.3rc1 (http://hg.python.org/cpython/file/3c4a5dc29417/Misc/NEWS). > > I have to get to work so I don't have time to fix this, but if someone > does have the time to unwind this mix-up that has accumulated that > would be great. And maybe it's finally time to bite the bullet and > come up with some way to automatically generate Misc/NEWS from commit > messages. No, commit messages do not a NEWS file make. The audiences are different (current and future developers vs interested end users), so it doesn't make sense to try to use the same content. Using commit messages also makes it annoyingly difficult to edit erroneous entries, as well as needing to come up with conventions to indicate commits which *shouldn't* get a log entry. What *does* make sense is to use a directory structure (which version control systems handle nicely) rather than a single file (which is prone to spurious context based conflicts). Twisted has their notion of "topfiles (see https://twistedmatrix.com/trac/wiki/ReviewProcess#Newsfiles) and for Beaker we adopted the model of simply dumping draft release note snippets into a "whatsnew/next" subdirectory and using a Sphinx wildcard to display them in the draft docs (we edit them into something more coherent as part of the release process, since they're our equivalent of What's New rather than NEWS). For Python, it would make sense to me if we took the existing subcategories in NEWS and turned them into a NEWS.in directory tree: NEWS.in/ legacy.txt # The NEWS contents from past releases 3.4.0a1/ core/ misc.txt # Any changes with no tracker entry issue12345.txt # Single bullet point issue54321.txt # Single bullet point ... library/ ... tests/ ... docs/ ... c-api/ ... idle/ ... build/ ... The trunk NEWS.in would then end up with full notes for all branches that have been merged forward. The NEWS file generation for each version would be designed to take care of matching up the corresponding maintenance releases when deciding which entries to include. Of course, we've talked about doing something like this before, it's just never irritated anyone enough for them to sit down and *write* the associated NEWS file generator, or the code to split the existing NEWS file for the active branches :) Cheers, Nick. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia ___ python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
Re: [python-committers] what's going on with Misc/NEWS?
24.05.13 15:24, Brett Cannon написав(ла): I was trying to do a simple merge of a doc change between 3.3 and default and the usual Misc/NEWS conflict came up. But when I looked at the diff it was massive! Turns out that Misc/NEWS in default goes from 3.3.1rc1 to 3.4.0a1 (http://hg.python.org/cpython/file/24ffb0148729/Misc/NEWS) while Misc/NEWS in 3.3 goes properly through all versions between 3.3.1rc1 to 3.3.3rc1 (http://hg.python.org/cpython/file/3c4a5dc29417/Misc/NEWS). I have to get to work so I don't have time to fix this, but if someone does have the time to unwind this mix-up that has accumulated that would be great. And maybe it's finally time to bite the bullet and come up with some way to automatically generate Misc/NEWS from commit messages. I had untangled some Misc/NEWS defects in issue17221 [1] but the work is not finished yet. [1] http://bugs.python.org/issue17221 ___ python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
Re: [python-committers] what's going on with Misc/NEWS?
On Fri, May 24, 2013 at 9:00 AM, Nick Coghlan wrote: > On Fri, May 24, 2013 at 10:24 PM, Brett Cannon wrote: >> I was trying to do a simple merge of a doc change between 3.3 and >> default and the usual Misc/NEWS conflict came up. But when I looked at >> the diff it was massive! Turns out that Misc/NEWS in default goes from >> 3.3.1rc1 to 3.4.0a1 >> (http://hg.python.org/cpython/file/24ffb0148729/Misc/NEWS) while >> Misc/NEWS in 3.3 goes properly through all versions between 3.3.1rc1 >> to 3.3.3rc1 (http://hg.python.org/cpython/file/3c4a5dc29417/Misc/NEWS). >> >> I have to get to work so I don't have time to fix this, but if someone >> does have the time to unwind this mix-up that has accumulated that >> would be great. And maybe it's finally time to bite the bullet and >> come up with some way to automatically generate Misc/NEWS from commit >> messages. > > No, commit messages do not a NEWS file make. The audiences are > different (current and future developers vs interested end users), so > it doesn't make sense to try to use the same content. Using commit > messages also makes it annoyingly difficult to edit erroneous entries, > as well as needing to come up with conventions to indicate commits > which *shouldn't* get a log entry. I don't know about you, but my first sentence (i.e. up to \n\n) is essentially what I put into NEWS anyway so making it work so that developer details go after that is not really an issue. Yes, coming up with a way to flag commits as not NEWS-worthy would be needed, but I don't think that would be difficult. > > What *does* make sense is to use a directory structure (which version > control systems handle nicely) rather than a single file (which is > prone to spurious context based conflicts). I sent a followup email to myself but unfortunately Gmail sent it from another address so it got rejected. > Twisted has their notion > of "topfiles (see > https://twistedmatrix.com/trac/wiki/ReviewProcess#Newsfiles) and for > Beaker we adopted the model of simply dumping draft release note > snippets into a "whatsnew/next" subdirectory and using a Sphinx > wildcard to display them in the draft docs (we edit them into > something more coherent as part of the release process, since they're > our equivalent of What's New rather than NEWS). > > For Python, it would make sense to me if we took the existing > subcategories in NEWS and turned them into a NEWS.in directory tree: > > NEWS.in/ > legacy.txt # The NEWS contents from past releases > 3.4.0a1/ > core/ > misc.txt # Any changes with no tracker entry > issue12345.txt # Single bullet point > issue54321.txt # Single bullet point > ... > library/ > ... > tests/ > ... > docs/ > ... > c-api/ > ... > idle/ > ... > build/ > ... > > The trunk NEWS.in would then end up with full notes for all branches > that have been merged forward. The NEWS file generation for each > version would be designed to take care of matching up the > corresponding maintenance releases when deciding which entries to > include. > > Of course, we've talked about doing something like this before, it's > just never irritated anyone enough for them to sit down and *write* > the associated NEWS file generator, or the code to split the existing > NEWS file for the active branches :) I think that's overly complicated. I don't see why we need anything more than simply NEWS/3.4, NEWS/3.3, etc. and just split the files per feature release since that's the interest (and merge) boundary. And do we really need a merged NEWS file at that granularity? ___ python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
Re: [python-committers] what's going on with Misc/NEWS?
Brett wrote: >> Of course, we've talked about doing something like this before, it's >> just never irritated anyone enough for them to sit down and *write* >> the associated NEWS file generator, or the code to split the existing >> NEWS file for the active branches :) > > I think that's overly complicated. Agreed. I'm not surprised Twisted uses something like that :-), but we don't need that level of complexity. > I don't see why we need anything > more than simply NEWS/3.4, NEWS/3.3, etc. and just split the files per > feature release since that's the interest (and merge) boundary. 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. * 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). 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 :-) > And do > we really need a merged NEWS file at that granularity? Not really, IMO. Regards Antoine. ___ python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
Re: [python-committers] what's going on with Misc/NEWS?
On Fri, 24 May 2013 18:39:16 +0200, "Antoine Pitrou" wrote: > Brett wrote: > >> Of course, we've talked about doing something like this before, it's > >> just never irritated anyone enough for them to sit down and *write* > >> the associated NEWS file generator, or the code to split the existing > >> NEWS file for the active branches :) > > > > I think that's overly complicated. > > Agreed. I'm not surprised Twisted uses something like that :-), but we > don't need > that level of complexity. > > > I don't see why we need anything > > more than simply NEWS/3.4, NEWS/3.3, etc. and just split the files per > > feature release since that's the interest (and merge) boundary. > > 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. > > * 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). > > 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 :-) I agree with Antoine here. I'd rather deal with the occasional conflicts (which goes: revert Misc/NEWS change, copy news entry) and get automatic merge some of the time, rather than have to *always* remember to copy the news entry, with no warning if I forget. The current way either the merge works[*], or you get an error reminding you you have to do the revert/copy dance. --David [*] So far I haven't had a case of what sometimes happened in svn, where the merge would appear to work but would be in the wrong section. I think this is because we moved stuff to HISTORY, or it may be that hg merge is just smarter than svn merge. ___ python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
Re: [python-committers] what's going on with Misc/NEWS?
On 5/24/2013 8:24 AM, Brett Cannon wrote: I was trying to do a simple merge of a doc change between 3.3 and default and the usual Misc/NEWS conflict came up. I have had things like this happen and after pain iwth kdiff3 just edited the default version But when I looked at the diff it was massive! Turns out that Misc/NEWS in default goes from 3.3.1rc1 to 3.4.0a1 (http://hg.python.org/cpython/file/24ffb0148729/Misc/NEWS) while Misc/NEWS in 3.3 goes properly through all versions between 3.3.1rc1 to 3.3.3rc1 (http://hg.python.org/cpython/file/3c4a5dc29417/Misc/NEWS). I do not know if I had the same cause. Never looked that far. I have to get to work so I don't have time to fix this, but if someone does have the time to unwind this mix-up that has accumulated that would be great. And maybe it's finally time to bite the bullet and come up with some way to automatically generate Misc/NEWS from commit messages. +100 on ending or ameliorating NEWS conflict hell. I do fewer commits because of it. Proposal: If the commit message has a line like ***Library then everything *above that line is put into NEWS. This makes automatic generation optional and optionally allows additional non-NEWS extras. The immediate problem is conflict with the lower context, the three lines below Library - which is often different between 3.3 and 3.4 and possibly changed anyway since the patch was made. Can hg be told to ignore the lower context and just match the 3 upper context lines for this file? The larger problem is that our workplace design subverts the premise of non-checkout repositories, that people usually work on different areas of files, making conflicts rare. Our current design makes conflict normal. -- Terry Jan Reedy ___ python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
Re: [python-committers] what's going on with Misc/NEWS?
On Fri, May 24, 2013 at 12:39 PM, Antoine Pitrou wrote: > > Brett wrote: >>> Of course, we've talked about doing something like this before, it's >>> just never irritated anyone enough for them to sit down and *write* >>> the associated NEWS file generator, or the code to split the existing >>> NEWS file for the active branches :) >> >> I think that's overly complicated. > > Agreed. I'm not surprised Twisted uses something like that :-), but we > don't need > that level of complexity. > >> I don't see why we need anything >> more than simply NEWS/3.4, NEWS/3.3, etc. and just split the files per >> feature release since that's the interest (and merge) boundary. > > 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; at least today it said I had to either resolve the conflict or do an update -C which tosses the whole change which is just annoying. > > * 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). 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. > > 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? -Brett > >> And do >> we really need a merged NEWS file at that granularity? > > Not really, IMO. > > Regards > > Antoine. > > > ___ > python-committers mailing list > python-committers@python.org > http://mail.python.org/mailman/listinfo/python-committers ___ python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
Re: [python-committers] what's going on with Misc/NEWS?
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 Misc/NEWS > > * 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. > 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? > > 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... :-) Regards Antoine. ___ python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
Re: [python-committers] what's going on with Misc/NEWS?
On Fri, May 24, 2013 at 2:27 PM, Antoine Pitrou 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 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. ___ python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
Re: [python-committers] what's going on with Misc/NEWS?
Le vendredi 24 mai 2013 à 15:26 -0400, Brett Cannon a écrit : > >> 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. I don't understand why it's painful to backport. Can you explain? ___ python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
Re: [python-committers] what's going on with Misc/NEWS?
On 5/24/2013 9:00 AM, Nick Coghlan wrote:
On Fri, May 24, 2013 at 10:24 PM, Brett Cannon wrote:
would be great. And maybe it's finally time to bite the bullet and
come up with some way to automatically generate Misc/NEWS from commit
messages.
No, commit messages do not a NEWS file make.
They often do. Nearly all of my NEWS messages are copy and paste from
the commit message. This is often true of other people's commits.
Anyway, my proposal, in response to Brett, is to make autocommit
optional and possible partial bu only autocommitting the part of a
commit message above a flag line like ***Library that identifies where
to put the autocommit. This proposal does not conflict with separating
the files.
The audiences are
different (current and future developers vs interested end users), so
it doesn't make sense to try to use the same content. Using commit
messages also makes it annoyingly difficult to edit erroneous entries,
It is impossible to correct commit messages now. Any error not noticed
before copy and paste already gets put in NEWS. Errors in NEWS could
still be corrected. Auto copy and paste does not change anything except
the hell of lower context conflict.
as well as needing to come up with conventions to indicate commits
which *shouldn't* get a log entry.
My proposed default is no autocommit. If you do not want it for your
commits, continue as present.
What *does* make sense is to use a directory structure (which version
Since the conflict problem is entirely within the sections that would be
put into separate files, I do not see how that affects the conflict
problem at all. This seems to me like an orthogonal proposal.
Here is an alternate proposal. Each branch has a NewsLog file. Each
entry consists of
---
TAG
Entry
---
TAG is CORE, LIB, IDLE, TEST, or DOC. The three blank lines are part of
the patch. Entries are put at the bottom of the file, so that the patch
context is (should be) 3 blank lines above and below.
No conflict possible (unless differs subvert this by thinking the old
blank lines are new and the new blank lines are old - maybe a commit
hook could check and correct this).
When releases are tagged, NewsLog is emptied, the entries are sorted by
tag and formatted
('- ' and ' ' prepended), subsection headers are added, and a
corresponding section is added to NEWS.
Of course, we've talked about doing something like this before, it's
just never irritated anyone enough for them to sit down and *write*
the associated NEWS file generator, or the code to split the existing
NEWS file for the active branches :)
The problem irritated enough other people that the devguide contains the
suggestion to insert news items into a random place in the current list.
This only works when the section contains at least a few entries.
Having missed previous discussions, my impression has been that old
timers are so used to the current mess and experienced dealing with it
that it was useless for me to even say anything. So if I do not care
enough about an issue to suffer the commit pain, I leave it alone.
Thanks Brett of saying something. However, I can only suggest as I have
no idea how to implement a commit hook that would look at commit lines
for a flag line to auto cut and commit. I do not even know if that is
possible with hg.
---
Terry Jan Reedy
___
python-committers mailing list
python-committers@python.org
http://mail.python.org/mailman/listinfo/python-committers
Re: [python-committers] what's going on with Misc/NEWS?
On Fri, 24 May 2013 15:26:29 -0400, Brett Cannon wrote: > On Fri, May 24, 2013 at 2:27 PM, Antoine Pitrou 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 Misc/NEWS > > I'll add that to the devguide if it works for me next time. I find that I also have to do: hg resolve -m Misc/NEWS which I find to be a really obnoxious mis-feature of hg. > > 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. You're adding a NEWS entry for a single character doc typo? No wonder you don't like making doc fixes :) I only make news entries for doc changes when they are major or are changes to the doc *system*. --David ___ python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
Re: [python-committers] what's going on with Misc/NEWS?
On Fri, May 24, 2013 at 3:54 PM, Antoine Pitrou wrote: > Le vendredi 24 mai 2013 à 15:26 -0400, Brett Cannon a écrit : >> >> 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. > > 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 If you look at that process, it's a lot of VCS stuff to keep history, which I understand. But there are at least two steps that directly involve Misc/NEWS which could be automated/skipped if we used the commit message somehow. And the fixing of Misc/NEWS I irrationally hate since it happens every single time and could go away somehow if we chose to make it go away even if people continue to hate on commit messages as a solution. ___ python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
Re: [python-committers] what's going on with Misc/NEWS?
On Fri, May 24, 2013 at 4:18 PM, R. David Murray wrote: > On Fri, 24 May 2013 15:26:29 -0400, Brett Cannon wrote: >> On Fri, May 24, 2013 at 2:27 PM, Antoine Pitrou 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 Misc/NEWS >> >> I'll add that to the devguide if it works for me next time. > > I find that I also have to do: > > hg resolve -m Misc/NEWS > > which I find to be a really obnoxious mis-feature of hg. > >> > 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. > > You're adding a NEWS entry for a single character doc typo? No wonder > you don't like making doc fixes :) > > I only make news entries for doc changes when they are major or are > changes to the doc *system*. It's an extreme example, but for instance I added an entry for this sys.modules change where I just added a clarifying sentence. Probably not needed but wanted to make sure that people got the message they shouldn't replace sys.modules. ___ python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
Re: [python-committers] what's going on with Misc/NEWS?
Trying again, as my response 2 hours ago never showed up On 5/24/2013 8:24 AM, Brett Cannon wrote: I was trying to do a simple merge of a doc change between 3.3 and default and the usual Misc/NEWS conflict came up. I have had things like this happen and after pain iwth kdiff3 just edited the default version But when I looked at the diff it was massive! Turns out that Misc/NEWS in default goes from 3.3.1rc1 to 3.4.0a1 (http://hg.python.org/cpython/file/24ffb0148729/Misc/NEWS) while Misc/NEWS in 3.3 goes properly through all versions between 3.3.1rc1 to 3.3.3rc1 (http://hg.python.org/cpython/file/3c4a5dc29417/Misc/NEWS). I do not know if I had the same cause. Never looked that far. I have to get to work so I don't have time to fix this, but if someone does have the time to unwind this mix-up that has accumulated that would be great. And maybe it's finally time to bite the bullet and come up with some way to automatically generate Misc/NEWS from commit messages. +100 on ending or ameliorating NEWS conflict hell. I do fewer commits because of it. Proposal: If the commit message has a line like ***Library then everything *above that line is put into NEWS. This makes automatic generation optional and optionally allows additional non-NEWS extras. The immediate problem is conflict with the lower context, the three lines below Library - which is often different between 3.3 and 3.4 and possibly changed anyway since the patch was made. Can hg be told to ignore the lower context and just match the 3 upper context lines for this file? The larger problem is that our workplace design subverts the premise of non-checkout repositories, that people usually work on different areas of files, making conflicts rare. Our current design makes conflict normal. -- Terry Jan Reedy ___ python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
Re: [python-committers] what's going on with Misc/NEWS?
2013/5/24 Brett Cannon : > It's an extreme example, but for instance I added an entry for this > sys.modules change where I just added a clarifying sentence. Probably > not needed but wanted to make sure that people got the message they > shouldn't replace sys.modules. Does anybody actually ready Misc/NEWS? -- Regards, Benjamin ___ python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
Re: [python-committers] what's going on with Misc/NEWS?
Another replay that did not show up on list.
On 5/24/2013 9:00 AM, Nick Coghlan wrote:
On Fri, May 24, 2013 at 10:24 PM, Brett Cannon wrote:
would be great. And maybe it's finally time to bite the bullet and
come up with some way to automatically generate Misc/NEWS from commit
messages.
No, commit messages do not a NEWS file make.
They often do. Nearly all of my NEWS messages are copy and paste from
the commit message. This is often true of other people's commits.
Anyway, my proposal, in response to Brett, is to make autocommit
optional and possible partial bu only autocommitting the part of a
commit message above a flag line like ***Library that identifies where
to put the autocommit. This proposal does not conflict with separating
the files.
The audiences are
different (current and future developers vs interested end users), so
it doesn't make sense to try to use the same content. Using commit
messages also makes it annoyingly difficult to edit erroneous entries,
It is impossible to correct commit messages now. Any error not noticed
before copy and paste already gets put in NEWS. Errors in NEWS could
still be corrected. Auto copy and paste does not change anything except
the hell of lower context conflict.
as well as needing to come up with conventions to indicate commits
which *shouldn't* get a log entry.
My proposed default is no autocommit. If you do not want it for your
commits, continue as present.
What *does* make sense is to use a directory structure (which version
Since the conflict problem is entirely within the sections that would be
put into separate files, I do not see how that affects the conflict
problem at all. This seems to me like an orthogonal proposal.
Here is an alternate proposal. Each branch has a NewsLog file. Each
entry consists of
---
TAG
Entry
---
TAG is CORE, LIB, IDLE, TEST, or DOC. The three blank lines are part of
the patch. Entries are put at the bottom of the file, so that the patch
context is (should be) 3 blank lines above and below.
No conflict possible (unless differs subvert this by thinking the old
blank lines are new and the new blank lines are old - maybe a commit
hook could check and correct this).
When releases are tagged, NewsLog is emptied, the entries are sorted by
tag and formatted
('- ' and ' ' prepended), subsection headers are added, and a
corresponding section is added to NEWS.
Of course, we've talked about doing something like this before, it's
just never irritated anyone enough for them to sit down and *write*
the associated NEWS file generator, or the code to split the existing
NEWS file for the active branches
The problem irritated enough other people that the devguide contains the
suggestion to insert news items into a random place in the current list.
This only works when the section contains at least a few entries.
Having missed previous discussions, my impression has been that old
timers are so used to the current mess and experienced dealing with it
that it was useless for me to even say anything. So if I do not care
enough about an issue to suffer the commit pain, I leave it alone.
Thanks Brett of saying something. However, I can only suggest as I have
no idea how to implement a commit hook that would look at commit lines
for a flag line to auto cut and commit. I do not even know if that is
possible with hg.
---
Terry Jan Reedy
___
python-committers mailing list
python-committers@python.org
http://mail.python.org/mailman/listinfo/python-committers
Re: [python-committers] what's going on with Misc/NEWS?
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?? Regards Antoine. ___ python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
Re: [python-committers] what's going on with Misc/NEWS?
On May 24, 2013 2:26 PM, "Benjamin Peterson" wrote: > > 2013/5/24 Brett Cannon : > > It's an extreme example, but for instance I added an entry for this > > sys.modules change where I just added a clarifying sentence. Probably > > not needed but wanted to make sure that people got the message they > > shouldn't replace sys.modules. > > Does anybody actually read Misc/NEWS? > Yes. It's the best way to get a summary of what changed in a release with more little details than any higher level what's new docs and without looking at diffs. > > -- > Regards, > Benjamin > ___ > python-committers mailing list > python-committers@python.org > http://mail.python.org/mailman/listinfo/python-committers ___ python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
Re: [python-committers] what's going on with Misc/NEWS?
On May 24, 2013 2:55 PM, "Antoine Pitrou" 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. 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. > > Regards > > Antoine. > > > ___ > python-committers mailing list > python-committers@python.org > http://mail.python.org/mailman/listinfo/python-committers ___ python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
Re: [python-committers] what's going on with Misc/NEWS?
On Fri, 24 May 2013 15:16:24 -0600, "Gregory P. Smith" wrote: > On May 24, 2013 2:55 PM, "Antoine Pitrou" 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 ___ python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
Re: [python-committers] what's going on with Misc/NEWS?
On 25 May 2013 13:05, "R. David Murray" wrote: > > On Fri, 24 May 2013 15:16:24 -0600, "Gregory P. Smith" wrote: > > On May 24, 2013 2:55 PM, "Antoine Pitrou" 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. Yep, that's my view of commit vs NEWS as well. Cheers, Nick. > > --David > > ___ > python-committers mailing list > python-committers@python.org > http://mail.python.org/mailman/listinfo/python-committers > ___ python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
Re: [python-committers] what's going on with Misc/NEWS?
On May 24, 2013, at 7:09 AM, Brett Cannon wrote: > I think that's overly complicated. I don't see why we need anything > more than simply NEWS/3.4, NEWS/3.3, etc. and just split the files per > feature release since that's the interest (and merge) boundary. +1 from me. This is a straight-forward solution to the merge problem and it recognizes that users don't really need to look across merge boundaries. Raymond___ python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
Re: [python-committers] what's going on with Misc/NEWS?
On Fri, May 24, 2013 at 9:46 PM, Raymond Hettinger wrote: > and it recognizes that users don't really need to look across merge > boundaries. This is tricky though for any patch that is forward-ported to a release branch (a la 3.2->3.3). How can you tell from MISC/News in which release (e.g. 3.3.0 or 3.3.1) of that branch the bug was fixed? The entry would only show up in MISC/News for the previous release (e.g. 3.2.3). Granted, this would impact much fewer patches than our current pain point does. -eric ___ python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
