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.
On Fri, May 24, 2013 at 10:24 PM, Brett Cannon brett@python.org 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 | ncoghlan@gmail.com | Brisbane, Australia
On Fri, May 24, 2013 at 9:00 AM, Nick Coghlan ncoghlan@gmail.com wrote:
On Fri, May 24, 2013 at 10:24 PM, Brett Cannon brett@python.org 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?
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.
On Fri, 24 May 2013 18:39:16 +0200, "Antoine Pitrou" solipsis@pitrou.net 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.
On Fri, May 24, 2013 at 12:39 PM, Antoine Pitrou solipsis@pitrou.net 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
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
- 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.
On Fri, May 24, 2013 at 2:27 PM, Antoine Pitrou solipsis@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.
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?
On Fri, May 24, 2013 at 3:54 PM, Antoine Pitrou solipsis@pitrou.net 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.
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.
On May 24, 2013 2:55 PM, "Antoine Pitrou" solipsis@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.
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
On Fri, 24 May 2013 15:16:24 -0600, "Gregory P. Smith" greg@krypto.org wrote:
On May 24, 2013 2:55 PM, "Antoine Pitrou" solipsis@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
On 25 May 2013 13:05, "R. David Murray" rdmurray@bitdance.com wrote:
On Fri, 24 May 2013 15:16:24 -0600, "Gregory P. Smith" greg@krypto.org
wrote:
On May 24, 2013 2:55 PM, "Antoine Pitrou" solipsis@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.
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
On Fri, 24 May 2013 15:26:29 -0400, Brett Cannon brett@python.org wrote:
On Fri, May 24, 2013 at 2:27 PM, Antoine Pitrou solipsis@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.
I find that I also have to do:
hg resolve -m Misc/NEWSwhich 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
On Fri, May 24, 2013 at 4:18 PM, R. David Murray rdmurray@bitdance.com wrote:
On Fri, 24 May 2013 15:26:29 -0400, Brett Cannon brett@python.org wrote:
On Fri, May 24, 2013 at 2:27 PM, Antoine Pitrou solipsis@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.
I find that I also have to do:
hg resolve -m Misc/NEWSwhich 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.
2013/5/24 Brett Cannon brett@python.org:
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
On May 24, 2013 2:26 PM, "Benjamin Peterson" benjamin@python.org wrote:
2013/5/24 Brett Cannon brett@python.org:
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
On Fri, May 24, 2013 at 7:39 PM, Antoine Pitrou solipsis@pitrou.net 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.
Agreed.
For me, in the best case scenario hg takes care of the merge; in the worst, kdiff3 pops up and I have to press CTRL and 3, 2, s, q (to include the two conflicting news, save and quit respectively). Solving the merge conflict is not something that really bothers me, and even when hg merge screws up, doing a revert and copying the news entry manually is not really cumbersome (and it doesn't happen really often anyway).
I understand that some people don't use and/or they are not sure how to use merge tools, but spending 10 minutes to install kdiff3 (or similar tools) and learn how to use it is a good investment IMHO*.
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 :-)
This is somewhere on my TODO list but even though hacking on Mercurial is a lot of fun, its priority is quite low since this "issue" doesn't affect me. I'm also not entirely sure what people want -- having separate files for every major version and an extension that merges the news entry in the right file should also be doable.
And do we really need a merged NEWS file at that granularity?
Not really, IMO.
I'm +0 on having a separate file for 3.3, 3.4, etc., as long as I don't have to copy/paste the news entry in the right file every time. Anything more than that is just going to cause more troubles.
Best Regards, Ezio Melotti
As I side note, before committing I always do an "hg diff" to check that everything is OK. Misc/NEWS is usually the last file in the diff, so I just copy the first sentence of the entry and use it in the commit message.
- this is also valid with Mercurial in general, but there's no need I tell you this ;)
On May 24, 2013, at 7:09 AM, Brett Cannon brett@python.org 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
On Fri, May 24, 2013 at 9:46 PM, Raymond Hettinger raymond.hettinger@gmail.com 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
On Sat, May 25, 2013 at 2:01 PM, Eric Snow ericsnowcurrently@gmail.com wrote:
On Fri, May 24, 2013 at 9:46 PM, Raymond Hettinger raymond.hettinger@gmail.com 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.
Let's take a step back for a moment and define the workflows we want to handle.
- Feature development
- simplest case
- just edit Misc/NEWS on default
- Normal 3.x only bug fix
- second simplest case
- exit Misc/NEWS on 3.3
- merge to default
- frequently conflict (due to entries for new features and different release headers) ....
OK, I'm going to stop enumerating the cases there, because it already suggests to me that splitting the *whole* NEWS file entirely by version is the wrong thing to do. Instead, we really only need to split the handling for NEWS items that haven't been released yet.
To avoid needing to copy info from other branches between files when doing a merge, we could instead set up the following:
- Add a new directory called NEWS.next
- New NEWS entries go in version specific files in that directory
- When a new release is made, ALL entries in NEWS.next are added to the top of the main NEWS file for the relevant (a script to help with the merging would be a good idea) and the contents of NEWS.next are cleared.
So, suppose we're about to release 3.4.0a1. In the meantime, we have accumulated bug fixes for 3.3 and new features and bug fixes that couldn't be backported for 3.4. (The scheme could be extended to security branches too, but I'm assuming for the moment those will be handled via selective backporting rather than the normal forward porting path)
The 3.3 branch layout would look like this:
NEWS.next/
3.3.txt # Categorised changes
NEWS # Existing partial entry for 3.3.xThe default branch layout would look like this:
NEWS.next/
3.3.txt # Forward ported categorised changes
3.4.txt # Categorised changesNEWS # Existing partial entry for 3.4.0a1
Any changes that were specific to 3.3 would be listed in NEWS.next/3.3.txt on that branch, but not on the default branch (since the associated null-merge would have skipped adding them)
Now, we go to create 3.4.0a1. This will involve transferring *all* the NEWS.next entries on default into the main NEWS file and clearing the files in NEWS.next.
NEWS.next/
3.3.txt # Empty file
3.4.txt # Empty fileNEWS # Complete entry for 3.4.0
The part I'm not clear on is whether we'd then start getting conflicts when forwarding merging changes to NEWS.next/3.3.txt from the 3.3 branch, or if Mercurial would be smart enough to cope with the deletion for the file contents and not try to add them back in. If it can't cope, then it would be possible to do the following on 3.3 when creating the initial 3.4.0a1 release:
NEWS.next/
3.3.txt # Empty fileNEWS # Longer partial entry for 3.3.x
We then continuing accumulating NEWS.next entries in parallel during the 3.4 alpha and beta cycle, moving the entries into the appropriate NEWS files as releases are made.
The other advantage of this is that it's an approach we can adopt *today*, so long as we acknowledge we'll need the tooling to merge the NEWS entries and clear NEWS.next before we can next do a release for 3.3 and 3.4, and Georg and Larry are happy with that notion.
Cheers, Nick.
-- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On Sat, May 25, 2013 at 4:40 AM, Nick Coghlan ncoghlan@gmail.com wrote:
On Sat, May 25, 2013 at 2:01 PM, Eric Snow ericsnowcurrently@gmail.com wrote:
On Fri, May 24, 2013 at 9:46 PM, Raymond Hettinger raymond.hettinger@gmail.com 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.
Let's take a step back for a moment and define the workflows we want to handle.
- Feature development
- simplest case
- just edit Misc/NEWS on default
- Normal 3.x only bug fix
- second simplest case
- exit Misc/NEWS on 3.3
- merge to default
- frequently conflict (due to entries for new features and different release headers) ....
OK, I'm going to stop enumerating the cases there, because it already suggests to me that splitting the *whole* NEWS file entirely by version is the wrong thing to do. Instead, we really only need to split the handling for NEWS items that haven't been released yet.
Yes, that's a very good point.
To avoid needing to copy info from other branches between files when doing a merge, we could instead set up the following:
- Add a new directory called NEWS.next
- New NEWS entries go in version specific files in that directory
- When a new release is made, ALL entries in NEWS.next are added to the top of the main NEWS file for the relevant (a script to help with the merging would be a good idea) and the contents of NEWS.next are cleared.
Still with you.
So, suppose we're about to release 3.4.0a1. In the meantime, we have accumulated bug fixes for 3.3 and new features and bug fixes that couldn't be backported for 3.4. (The scheme could be extended to security branches too, but I'm assuming for the moment those will be handled via selective backporting rather than the normal forward porting path)
The 3.3 branch layout would look like this:
NEWS.next/ 3.3.txt # Categorised changes
Categorized how? E.g. Core,Lib,Docs, etc.? Or "3.3 only", "3.3 and 3.4"?
NEWS # Existing partial entry for 3.3.x
And the accumulated history of all previous versions.
The default branch layout would look like this:
NEWS.next/ 3.3.txt # Forward ported categorised changes 3.4.txt # Categorised changesNEWS # Existing partial entry for 3.4.0a1
Any changes that were specific to 3.3 would be listed in NEWS.next/3.3.txt on that branch, but not on the default branch (since the associated null-merge would have skipped adding them)
Now, we go to create 3.4.0a1. This will involve transferring *all* the NEWS.next entries on default into the main NEWS file and clearing the files in NEWS.next.
NEWS.next/ 3.3.txt # Empty file 3.4.txt # Empty fileNEWS # Complete entry for 3.4.0
The part I'm not clear on is whether we'd then start getting conflicts when forwarding merging changes to NEWS.next/3.3.txt from the 3.3 branch, or if Mercurial would be smart enough to cope with the deletion for the file contents and not try to add them back in. If it can't cope, then it would be possible to do the following on 3.3 when creating the initial 3.4.0a1 release:
NEWS.next/ 3.3.txt # Empty fileNEWS # Longer partial entry for 3.3.x
Right, and that's the tricky bit. You can have a 3.3 file which is stuff that is not forward-ported (and thus just delete the file in default and won't hg just ignore the diff for that file?) and you can have a 3.4 file that only exists in default so you don't have to worry about any merge issues.
But it's the 3.3+ changes that exist in both versions. That's the sticking point and where we always have merge problems. We might want to classify commits as 3.3 only, 3.3+3.4, or 3.4 only and have separate files for each case.
Since these files are for staging NEWS entries essentially and are not meant to be seen by the general public, we can be a little messy here. So why don't we simply use markers in a 3.3+3.4 file that gets merged across 3.3 and default that represents "from this line down, everything has been merged into the main NEWS file under 3.4" and then some other line that represents "from this line down everything has been merged into the main NEWS file for 3.3". Then above those lines we just start a new set of sections we continue to populate every time there is some merger in some version for NEWS. A script can easily figure out that some region is new to 3.4 or 3.3 based on reasonable markers and just searching far enough back in the file to the last merge for a specific feature release. And who cares if we have a bazillion Library sections as long as the Library section at the top is where we always put new entries that go into 3.3 and 3.4? Then there is no merge conflict, no repeating ourselves and it's still easy to add NEWS entries.
We then continuing accumulating NEWS.next entries in parallel during the 3.4 alpha and beta cycle, moving the entries into the appropriate NEWS files as releases are made.
The other advantage of this is that it's an approach we can adopt *today*, so long as we acknowledge we'll need the tooling to merge the NEWS entries and clear NEWS.next before we can next do a release for 3.3 and 3.4, and Georg and Larry are happy with that notion.
Yes, it's yet another step for release managers, but if we tool it right and add it to release.py the burden should be low to non-existent (biggest issue would be resolving the potential merge conflict from 3.3 to default after a release when the main NEWS file is updated).
On Sun, May 26, 2013 at 1:10 AM, Brett Cannon brett@python.org wrote:
On Sat, May 25, 2013 at 4:40 AM, Nick Coghlan ncoghlan@gmail.com wrote:
The 3.3 branch layout would look like this:
NEWS.next/ 3.3.txt # Categorised changesCategorized how? E.g. Core,Lib,Docs, etc.? Or "3.3 only", "3.3 and 3.4"?
Just the existing categories. So Core, Library, etc
NEWS # Existing partial entry for 3.3.xAnd the accumulated history of all previous versions.
Indeed.
But it's the 3.3+ changes that exist in both versions. That's the sticking point and where we always have merge problems. We might want to classify commits as 3.3 only, 3.3+3.4, or 3.4 only and have separate files for each case.
Yeah, I think that makes sense - we're going to know which we have before we create the news entry, so how about if the layout looked like this:
3.3 branch layout:
NEWS.next/
3.3.txt # Forward ported
3.3-only.txt # Not forward ported
NEWS # Existing partial entry for 3.3.xThe default branch layout would look like this:
NEWS.next/
3.3.txt # Forward ported changes
3.4.txt # All 3.4 changesNEWS # Existing partial entry for 3.4.0a1
Any changes that were specific to 3.3 would be listed in NEWS.next/3.3-only.txt on that branch, but not on the default branch (since the associated null-merge would always skip adding that file)
Now, we go to create 3.4.0a1 with this layout. This will involve transferring *all* the NEWS.next entries on default into the main NEWS file and clearing the files in NEWS.next.
NEWS.next/
3.3.txt # Empty file
3.4.txt # Empty fileNEWS # Complete entry for 3.4.0
We then go back to the 3.3 branch, and move all of the NEWS.next/3.3.txt entries into NEWS.next/3.3-only.txt and do a null merge.
NEWS.next/
3.3.txt # Empty file
3.3-only.txt # Not forward ported or already released for 3.4
NEWS # Existing partial entry for 3.3.xWhen it comes time to create the next 3.3 release, the contents of both NEWS.next/3.3.txt and NEWS.next/3.3-only.txt would be merged into the main 3.3 NEWS file.
Does that seem workable?
Cheers, Nick.
-- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On May 25, 2013 1:40 AM, "Nick Coghlan" ncoghlan@gmail.com wrote:
On Sat, May 25, 2013 at 2:01 PM, Eric Snow ericsnowcurrently@gmail.com
On Fri, May 24, 2013 at 9:46 PM, Raymond Hettinger raymond.hettinger@gmail.com 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
wrote: point does.
Let's take a step back for a moment and define the workflows we want to
handle.
- Feature development
- simplest case
- just edit Misc/NEWS on default
- Normal 3.x only bug fix
- second simplest case
- exit Misc/NEWS on 3.3
- merge to default
- frequently conflict (due to entries for new features and different release headers) ....
OK, I'm going to stop enumerating the cases there, because it already suggests to me that splitting the *whole* NEWS file entirely by version is the wrong thing to do. Instead, we really only need to split the handling for NEWS items that haven't been released yet.
To avoid needing to copy info from other branches between files when doing a merge, we could instead set up the following:
- Add a new directory called NEWS.next
- New NEWS entries go in version specific files in that directory
- When a new release is made, ALL entries in NEWS.next are added to the top of the main NEWS file for the relevant (a script to help with the merging would be a good idea) and the contents of NEWS.next are cleared.
So, suppose we're about to release 3.4.0a1. In the meantime, we have accumulated bug fixes for 3.3 and new features and bug fixes that couldn't be backported for 3.4. (The scheme could be extended to security branches too, but I'm assuming for the moment those will be handled via selective backporting rather than the normal forward porting path)
The 3.3 branch layout would look like this:
NEWS.next/ 3.3.txt # Categorised changes NEWS # Existing partial entry for 3.3.xThe default branch layout would look like this:
NEWS.next/ 3.3.txt # Forward ported categorised changes 3.4.txt # Categorised changesNEWS # Existing partial entry for 3.4.0a1
Any changes that were specific to 3.3 would be listed in NEWS.next/3.3.txt on that branch, but not on the default branch (since the associated null-merge would have skipped adding them)
Now, we go to create 3.4.0a1. This will involve transferring *all* the NEWS.next entries on default into the main NEWS file and clearing the files in NEWS.next.
NEWS.next/ 3.3.txt # Empty file 3.4.txt # Empty fileNEWS # Complete entry for 3.4.0
The part I'm not clear on is whether we'd then start getting conflicts when forwarding merging changes to NEWS.next/3.3.txt from the 3.3 branch, or if Mercurial would be smart enough to cope with the deletion for the file contents and not try to add them back in. If it can't cope, then it would be possible to do the following on 3.3 when creating the initial 3.4.0a1 release:
NEWS.next/ 3.3.txt # Empty fileNEWS # Longer partial entry for 3.3.x
We then continuing accumulating NEWS.next entries in parallel during the 3.4 alpha and beta cycle, moving the entries into the appropriate NEWS files as releases are made.
The other advantage of this is that it's an approach we can adopt *today*, so long as we acknowledge we'll need the tooling to merge the NEWS entries and clear NEWS.next before we can next do a release for 3.3 and 3.4, and Georg and Larry are happy with that notion.
I like where you're heading with this but it still leaves merges during Spruits and when a few people are working at once by putting stuff in a single file.
Per news item / per issue files for each release that are riled up into the actual news file by a release manager run script & commit at release time make more sense.
Cheers, Nick.
-- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
On May 25, 2013 8:29 AM, "Gregory P. Smith" greg@krypto.org wrote:
On May 25, 2013 1:40 AM, "Nick Coghlan" ncoghlan@gmail.com wrote:
On Sat, May 25, 2013 at 2:01 PM, Eric Snow ericsnowcurrently@gmail.com
On Fri, May 24, 2013 at 9:46 PM, Raymond Hettinger raymond.hettinger@gmail.com 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
wrote: point does.
Let's take a step back for a moment and define the workflows we want to
handle.
- Feature development
- simplest case
- just edit Misc/NEWS on default
- Normal 3.x only bug fix
- second simplest case
- exit Misc/NEWS on 3.3
- merge to default
- frequently conflict (due to entries for new features and different release headers) ....
OK, I'm going to stop enumerating the cases there, because it already suggests to me that splitting the *whole* NEWS file entirely by version is the wrong thing to do. Instead, we really only need to split the handling for NEWS items that haven't been released yet.
To avoid needing to copy info from other branches between files when doing a merge, we could instead set up the following:
- Add a new directory called NEWS.next
- New NEWS entries go in version specific files in that directory
- When a new release is made, ALL entries in NEWS.next are added to the top of the main NEWS file for the relevant (a script to help with the merging would be a good idea) and the contents of NEWS.next are cleared.
So, suppose we're about to release 3.4.0a1. In the meantime, we have accumulated bug fixes for 3.3 and new features and bug fixes that couldn't be backported for 3.4. (The scheme could be extended to security branches too, but I'm assuming for the moment those will be handled via selective backporting rather than the normal forward porting path)
The 3.3 branch layout would look like this:
NEWS.next/ 3.3.txt # Categorised changes NEWS # Existing partial entry for 3.3.xThe default branch layout would look like this:
NEWS.next/ 3.3.txt # Forward ported categorised changes 3.4.txt # Categorised changesNEWS # Existing partial entry for 3.4.0a1
Any changes that were specific to 3.3 would be listed in NEWS.next/3.3.txt on that branch, but not on the default branch (since the associated null-merge would have skipped adding them)
Now, we go to create 3.4.0a1. This will involve transferring *all* the NEWS.next entries on default into the main NEWS file and clearing the files in NEWS.next.
NEWS.next/ 3.3.txt # Empty file 3.4.txt # Empty fileNEWS # Complete entry for 3.4.0
The part I'm not clear on is whether we'd then start getting conflicts when forwarding merging changes to NEWS.next/3.3.txt from the 3.3 branch, or if Mercurial would be smart enough to cope with the deletion for the file contents and not try to add them back in. If it can't cope, then it would be possible to do the following on 3.3 when creating the initial 3.4.0a1 release:
NEWS.next/ 3.3.txt # Empty fileNEWS # Longer partial entry for 3.3.x
We then continuing accumulating NEWS.next entries in parallel during the 3.4 alpha and beta cycle, moving the entries into the appropriate NEWS files as releases are made.
The other advantage of this is that it's an approach we can adopt *today*, so long as we acknowledge we'll need the tooling to merge the NEWS entries and clear NEWS.next before we can next do a release for 3.3 and 3.4, and Georg and Larry are happy with that notion.
I like where you're heading with this but it still leaves merges during Spruits and when a few people are working at once by putting stuff in a single file.
sprints
Per news item / per issue files for each release that are riled up into
the actual news file by a release manager run script & commit at release time make more sense.
Cheers, Nick.
-- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
On Sun, May 26, 2013 at 1:29 AM, Gregory P. Smith greg@krypto.org wrote:
I like where you're heading with this but it still leaves merges during Spruits and when a few people are working at once by putting stuff in a single file.
Per news item / per issue files for each release that are riled up into the actual news file by a release manager run script & commit at release time make more sense.
That's heading back to where I started, when people dismissed the idea as too complex. It's a pretty straightforward change to my previous suggestion though. Instead of having these layouts:
NEWS.next/
3.3.txt
3.3-only.txt
NEWS.next/
3.3.txt
3.4.txtYou instead have layouts like:
NEWS.next/
3.3/
core/
issue123456.txt # Core change with issue number
misc.txt # Core changes without issue numbers
library/
issue54321.txt # Library change with issue number
misc.txt # Library changes without issue numbers
...
3.3-only/
...
NEWS.next/
3.3/
...
3.4/
...Whether categorisation is done by file prefix or by directories doesn't make much difference, although I have a slight preference for separate folders since repeating prefixes feels like irrelevant noise.
The NEWS update script could even use the revision history to decide which order to add entries to the bulleted list.
Cheers, Nick.
-- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On Sat, May 25, 2013 at 12:05 PM, Nick Coghlan ncoghlan@gmail.com wrote:
On Sun, May 26, 2013 at 1:29 AM, Gregory P. Smith greg@krypto.org wrote:
I like where you're heading with this but it still leaves merges during Spruits and when a few people are working at once by putting stuff in a single file.
I don't know if sprints happen often enough to make them a big worry, but it's true they are there.
Per news item / per issue files for each release that are riled up into the actual news file by a release manager run script & commit at release time make more sense.
That's heading back to where I started, when people dismissed the idea as too complex. It's a pretty straightforward change to my previous suggestion though. Instead of having these layouts:
NEWS.next/ 3.3.txt 3.3-only.txt NEWS.next/ 3.3.txt 3.4.txtYou instead have layouts like:
NEWS.next/ 3.3/ core/ issue123456.txt # Core change with issue number misc.txt # Core changes without issue numbers library/ issue54321.txt # Library change with issue number misc.txt # Library changes without issue numbers ... 3.3-only/ ... NEWS.next/ 3.3/ ... 3.4/ ...Whether categorisation is done by file prefix or by directories doesn't make much difference, although I have a slight preference for separate folders since repeating prefixes feels like irrelevant noise.
Directory if this happens.
The NEWS update script could even use the revision history to decide which order to add entries to the bulleted list.
I think the annoyance with this approach is you will have to remember
to add a file every time you do anything worthy of NEWS. Without
something like hg newsworthy to take an optional issue # and then
have you enter your NEWS entry and then use that to pre-populate the
commit message, people will forget. Now granted adding the commit
later is not a huge deal, but it is something that might happen if you
forget to hg st before committing.
And if you go that route you start to end up with something like a marker to separate in the commit message what is meant for the commit and what is meant for NEWS.
On Sun, May 26, 2013 at 9:41 AM, Brett Cannon brett@python.org wrote:
The NEWS update script could even use the revision history to decide which order to add entries to the bulleted list.
I think the annoyance with this approach is you will have to remember to add a file every time you do anything worthy of NEWS. Without something like
hg newsworthyto take an optional issue # and then have you enter your NEWS entry and then use that to pre-populate the commit message, people will forget. Now granted adding the commit later is not a huge deal, but it is something that might happen if you forget tohg stbefore committing.
How is that any different from the status quo with people forgetting an entry in NEWS? Just the extra step of needing to "hg add" the news entry?
Well, perhaps we can do this in two phases - resolve the persistent problem of merge conflicts first, and then worry about the separate push race problem later.
Cheers, Nick.
-- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On May 25, 2013 9:18 PM, "Nick Coghlan" ncoghlan@gmail.com wrote:
On Sun, May 26, 2013 at 9:41 AM, Brett Cannon brett@python.org wrote:
The NEWS update script could even use the revision history to decide which order to add entries to the bulleted list.
I think the annoyance with this approach is you will have to remember to add a file every time you do anything worthy of NEWS. Without something like
hg newsworthyto take an optional issue # and then have you enter your NEWS entry and then use that to pre-populate the commit message, people will forget. Now granted adding the commit later is not a huge deal, but it is something that might happen if you forget tohg stbefore committing.How is that any different from the status quo with people forgetting an entry in NEWS? Just the extra step of needing to "hg add" the news entry?
I didn't think there was a forgetfulness issue. I'm just trying to lower the overhead of doing a merge.
Well, perhaps we can do this in two phases - resolve the persistent problem of merge conflicts first, and then worry about the separate push race problem later.
If we can ever agree on a solution. :)
-brett
Cheers, Nick.
-- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On May 26, 2013 1:15 PM, "Brett Cannon" brett@python.org wrote:
On May 25, 2013 9:18 PM, "Nick Coghlan" ncoghlan@gmail.com wrote:
On Sun, May 26, 2013 at 9:41 AM, Brett Cannon brett@python.org wrote:
The NEWS update script could even use the revision history to decide which order to add entries to the bulleted list.
I think the annoyance with this approach is you will have to remember to add a file every time you do anything worthy of NEWS. Without something like
hg newsworthyto take an optional issue # and then have you enter your NEWS entry and then use that to pre-populate the commit message, people will forget. Now granted adding the commit later is not a huge deal, but it is something that might happen if you forget tohg stbefore committing.How is that any different from the status quo with people forgetting an entry in NEWS? Just the extra step of needing to "hg add" the news entry?
I didn't think there was a forgetfulness issue. I'm just trying to lower
the overhead of doing a merge.
Well, perhaps we can do this in two phases - resolve the persistent problem of merge conflicts first, and then worry about the separate push race problem later.
If we can ever agree on a solution. :)
If people are still allowed to edit Misc/NEWS manually while a tools and alternatives are worked out that ultimately merge their entries into the original file at release time I think no agreement is needed beyond from the release managers who presumably get to ensure it all happens to generate the single file at tag/branch time.
Try a few things out, see what sticks and vote on what the ultimate solution for everyone should be at that point.
-brett
Cheers, Nick.
-- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On 5/24/2013 9:00 AM, Nick Coghlan wrote:
On Fri, May 24, 2013 at 10:24 PM, Brett Cannon brett@python.org 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 <bottom of file> 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
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 brett@python.org 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 <bottom of file> 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
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.
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
<blank>
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
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
<blank>
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
participants (11)
-
Antoine Pitrou -
Benjamin Peterson -
Brett Cannon -
Eric Snow -
Ezio Melotti -
Gregory P. Smith -
Nick Coghlan -
R. David Murray -
Raymond Hettinger -
Serhiy Storchaka -
Terry Reedy