Re: [sage-devel] Re: Changelogs in SPKG.txt
On 25 May 2010 20:58, Robert Bradshaw rober...@math.washington.edu wrote: On May 25, 2010, at 12:35 PM, kcrisman wrote: SPKG.txt version === r-2.10.1.p0 (David Kirkby, February 16th 2010) === Snip lots of stuff I wrote in an SPKG.txt file Are you really suggesting that the commit message should be this long? Maybe they should be! Yes, I've got no problem with long commit messages, the more info the better (especially for obscure build files and configure scripts, where the changes are far from self documenting). There are some nice commit messages in the combinat code too. If one is a Mercurial guru, then making long commit messages, changing them when one makes a mistake, finding out what someone else has done might all be pretty easy to you. But a simple text file is going to be a lot less intimidating for some (many?). In order to change the contents of the commit message one is going to need to know about queues I expect, since one will probably need to push/pop commit messages. I don't know what's involved. I've personally been happy with the long SPKG.txt, a short commit message. I usually edit SPKG.txt a few times, correct a few errors, then make a final small commit message, which I often make the trac number and trac title, though I'm not very rigid about this. Using Sage to fire up 'hg' is fine if Sage has built to that point, but its not a lot of use if you are trying to debug a problem occurring before Mercurial has been built. If one makes the argument that people should have Mercurial installed, then I don't see the point in having it a standard package. And I reiterate that I recall somewhere a suggestion on sage-devel that commit messages should be one line long. Does no one else remember that? Or did it mean it should not have any carriage returns, but be as long as it wants (in which case this was not clear at all)? Only the first line shows up by default so it should be self-contained and concise (so that the listings are short). hg log -v will show long commit messages, and hg log -p will print out the patches as well. - Robert Again, you know this, since you know Mercurial well. It was only a few months ago that I put a two or three line commit message and Ming (who is clearly very competent) said only the first line would be recorded. Someone (perhaps you) corrected him. I think there are two things to consider here: 1) What is technically possible with Mercurial 2) What will be understandable by a large fraction of Sage developers. I suspect (2) is a small subset of (1), so having a simple text file, and making the process as simple as possible, is useful. When I first started developing on Sage, I did not know Mercurial. I would makes the changes to the code, update SPKG.txt and get the release manager to update the repository. I suspect requiring informative commit messages will add to the complexity of this. But if the change is made, I wont think it the worst possible crime, but I'd certainly prefer the current simple text file Dave -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
Re: [sage-devel] Re: Changelogs in SPKG.txt
On 25 May 2010 20:58, Robert Bradshaw rober...@math.washington.edu wrote: On May 25, 2010, at 12:35 PM, kcrisman wrote: SPKG.txt version === r-2.10.1.p0 (David Kirkby, February 16th 2010) === Snip lots of stuff I wrote in an SPKG.txt file Are you really suggesting that the commit message should be this long? Maybe they should be! Yes, I've got no problem with long commit messages, the more info the better (especially for obscure build files and configure scripts, where the changes are far from self documenting). There are some nice commit messages in the combinat code too. If one is a Mercurial guru, then making long commit messages, changing them when one makes a mistake, finding out what someone else has done might all be pretty easy to you. But a simple text file is going to be a lot less intimidating for some (many?). I agree with that point of view. I have had lots of thoughts about the issue since the thread came up and my personal conclusion is that getting rid of simple text log will be a barrier to entry. It is fine to have a barrier for entry but you have to be sure that's what you want. Francois -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
Re: [sage-devel] Re: Changelogs in SPKG.txt
On Wed, May 26, 2010 at 3:30 AM, François Bissey f.r.bis...@massey.ac.nz wrote: On 25 May 2010 20:58, Robert Bradshaw rober...@math.washington.edu wrote: On May 25, 2010, at 12:35 PM, kcrisman wrote: SPKG.txt version === r-2.10.1.p0 (David Kirkby, February 16th 2010) === Snip lots of stuff I wrote in an SPKG.txt file Are you really suggesting that the commit message should be this long? Maybe they should be! Yes, I've got no problem with long commit messages, the more info the better (especially for obscure build files and configure scripts, where the changes are far from self documenting). There are some nice commit messages in the combinat code too. If one is a Mercurial guru, then making long commit messages, changing them when one makes a mistake, finding out what someone else has done might all be pretty easy to you. But a simple text file is going to be a lot less intimidating for some (many?). I agree with that point of view. I have had lots of thoughts about the issue since the thread came up and my personal conclusion is that getting rid of simple text log will be a barrier to entry. Your arguments would also suggest that any of the Sage repositories should have their logs in a text file as well. Should the main Sage Python library!? Should the local/bin/ repository have a text file? -- William -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
Re: [sage-devel] Re: Changelogs in SPKG.txt
On Wed, May 26, 2010 at 3:30 AM, François Bissey f.r.bis...@massey.ac.nz wrote: On 25 May 2010 20:58, Robert Bradshaw rober...@math.washington.edu wrote: On May 25, 2010, at 12:35 PM, kcrisman wrote: SPKG.txt version === r-2.10.1.p0 (David Kirkby, February 16th 2010) === Snip lots of stuff I wrote in an SPKG.txt file Are you really suggesting that the commit message should be this long? Maybe they should be! Yes, I've got no problem with long commit messages, the more info the better (especially for obscure build files and configure scripts, where the changes are far from self documenting). There are some nice commit messages in the combinat code too. If one is a Mercurial guru, then making long commit messages, changing them when one makes a mistake, finding out what someone else has done might all be pretty easy to you. But a simple text file is going to be a lot less intimidating for some (many?). I agree with that point of view. I have had lots of thoughts about the issue since the thread came up and my personal conclusion is that getting rid of simple text log will be a barrier to entry. Your arguments would also suggest that any of the Sage repositories should have their logs in a text file as well. Should the main Sage Python library!? Should the local/bin/ repository have a text file? I think you are heating up and pushing our argument in a direction which we would have considered silly. You obviously feel very strongly about this. Our point is that the new blood you are looking for will have to come with a knowledge of mercurial if they want to know what's going on. If in spkg.txt, or even in the README file at the top level, there are easy to follow instructions on how to extract useful info from mercurial log that may not be so bad. Francois -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
Re: [sage-devel] Re: Changelogs in SPKG.txt
On Wed, May 26, 2010 at 3:52 AM, François Bissey f.r.bis...@massey.ac.nz wrote: On Wed, May 26, 2010 at 3:30 AM, François Bissey f.r.bis...@massey.ac.nz wrote: On 25 May 2010 20:58, Robert Bradshaw rober...@math.washington.edu wrote: On May 25, 2010, at 12:35 PM, kcrisman wrote: SPKG.txt version === r-2.10.1.p0 (David Kirkby, February 16th 2010) === Snip lots of stuff I wrote in an SPKG.txt file Are you really suggesting that the commit message should be this long? Maybe they should be! Yes, I've got no problem with long commit messages, the more info the better (especially for obscure build files and configure scripts, where the changes are far from self documenting). There are some nice commit messages in the combinat code too. If one is a Mercurial guru, then making long commit messages, changing them when one makes a mistake, finding out what someone else has done might all be pretty easy to you. But a simple text file is going to be a lot less intimidating for some (many?). I agree with that point of view. I have had lots of thoughts about the issue since the thread came up and my personal conclusion is that getting rid of simple text log will be a barrier to entry. Your arguments would also suggest that any of the Sage repositories should have their logs in a text file as well. Should the main Sage Python library!? Should the local/bin/ repository have a text file? I think you are heating up and pushing our argument in a direction which we would have considered silly. I don't understand why it is silly. It seems like doing exactly the same thing to me. You obviously feel very strongly about this. Actually, I don't. Our point is that the new blood you are looking for will have to come with a knowledge of mercurial if they want to know what's going on. I agree. If in spkg.txt, or even in the README file at the top level, there are easy to follow instructions on how to extract useful info from mercurial log that may not be so bad. That's a great idea. In fact, I learned some things in this thread about how to use the hg log. William Francois -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org -- William Stein Professor of Mathematics University of Washington http://wstein.org -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
Re: [sage-devel] Re: Changelogs in SPKG.txt
On May 26, 2010, at 2:06 AM, David Kirkby wrote: On 25 May 2010 20:58, Robert Bradshaw rober...@math.washington.edu wrote: On May 25, 2010, at 12:35 PM, kcrisman wrote: SPKG.txt version === r-2.10.1.p0 (David Kirkby, February 16th 2010) === Snip lots of stuff I wrote in an SPKG.txt file Are you really suggesting that the commit message should be this long? Maybe they should be! Yes, I've got no problem with long commit messages, the more info the better (especially for obscure build files and configure scripts, where the changes are far from self documenting). There are some nice commit messages in the combinat code too. If one is a Mercurial guru, then making long commit messages, changing them when one makes a mistake, finding out what someone else has done might all be pretty easy to you. But a simple text file is going to be a lot less intimidating for some (many?). In order to change the contents of the commit message one is going to need to know about queues I expect, since one will probably need to push/pop commit messages. I don't know what's involved. I've personally been happy with the long SPKG.txt, a short commit message. I usually edit SPKG.txt a few times, correct a few errors, then make a final small commit message, which I often make the trac number and trac title, though I'm not very rigid about this. Using Sage to fire up 'hg' is fine if Sage has built to that point, but its not a lot of use if you are trying to debug a problem occurring before Mercurial has been built. If one makes the argument that people should have Mercurial installed, then I don't see the point in having it a standard package. Unless we start accepting spkgs with un-checked in changes, we're going to require a working mercurial for Sage development in any case. Learning mercurial is a requirement for developing Sage, there's no way around that. Personally, I would say anyone not using queues is at a disadvantage, and they're really easy to pick up (especially if you're just working on a single patch, rather than popping and pushing a whole stack). And I reiterate that I recall somewhere a suggestion on sage-devel that commit messages should be one line long. Does no one else remember that? Or did it mean it should not have any carriage returns, but be as long as it wants (in which case this was not clear at all)? Only the first line shows up by default so it should be self- contained and concise (so that the listings are short). hg log -v will show long commit messages, and hg log -p will print out the patches as well. - Robert Again, you know this, since you know Mercurial well. I know google well :). (Well, I knew it was possible, but forgot the option.) I especially like long commits when browsing repositories through the web interface (and on a tangential note, we should be providing an easier way to brows the source and repositories of the spkgs online). It was only a few months ago that I put a two or three line commit message and Ming (who is clearly very competent) said only the first line would be recorded. Someone (perhaps you) corrected him. I think there are two things to consider here: 1) What is technically possible with Mercurial 2) What will be understandable by a large fraction of Sage developers. I suspect (2) is a small subset of (1), so having a simple text file, and making the process as simple as possible, is useful. When I first started developing on Sage, I did not know Mercurial. I would makes the changes to the code, update SPKG.txt and get the release manager to update the repository. I suspect requiring informative commit messages will add to the complexity of this. But if the change is made, I wont think it the worst possible crime, but I'd certainly prefer the current simple text file Given William's reductio ad absurdum argument of using text files to keep track of the Sage library changes, it's clear that there are disadvantages of not using the revision control. On the other hand, even there we're really using trac as a glorified extension of our revision control to keep the extensive comments. Personally, I brought this up because it seems redundant to me to record changes in two places. Which one gets the good description? I hadn't realize some people don't like using mercurial so much. Here's another idea: 1) A clear description in SPKG.txt how to get the log. 2) We could add a line in SPKG.txt that says Anything below here will get added to the commit message on packaging... and then do so. Maybe this would just complicate things. I guess I don't feel that strongly about it, and clearly many people do feel strongly about using plain text files. I don't edit spkgs enough for it to matter much to me (other than Cython, where bumping the version is essentially the only thing I ever do). - Robert -- To post to this group, send an email to sage-devel@googlegroups.com To
Re: [sage-devel] Re: Changelogs in SPKG.txt
On May 26, 2010, at 11:55 AM, kcrisman wrote: way around that. Personally, I would say anyone not using queues is at a disadvantage, True. and they're really easy to pick up (especially if Not without having someone over your shoulder, which is why I still don't/can't use them. (Maybe Rob and Jason will finally teach me when they visit in June!). Sure. For a single patch, do hg qnew -f some_name # create a changeset hg qref -e # refresh the patch, including the commit message, as many times as you want hg qfinish tip # turn the patch into an actual commit What's the point with a single patch? I use a combination of rollback and --no-commit for now. For creating good commit messages. Also, they're handy if you want to try something out and that you want to easily be able to revert. Random remark: One reason why HG alone is much harder than in Sage is that there is no tab completion of the various HG commands, no interactive verbose help accessible as easily with a ?, etc. That has saved me in hg_sage many, many times. One note--you don't have to type the whole command, just enough to make it unique. (Not as good as tab completion, but nice). - Robert -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
Re: [sage-devel] Re: Changelogs in SPKG.txt
On May 26, 2010, at 12:49 PM, Jason Grout wrote: On 5/26/10 5:33 AM, William Stein wrote: Your arguments would also suggest that any of the Sage repositories should have their logs in a text file as well. Should the main Sage Python library!? Should the local/bin/ repository have a text file? You know, for certain things, this might not be a bad idea. For example, we have no listing of compatibility breakages between Sage versions, which has often tripped things up for me and others that I know. If there was a simple changelog mentioning big changes that might break people's code, then it would be much easier for an enduser to know if they should upgrade, or know how to fix their code if they did upgrade. Yes, I know there should be deprecation warnings for every change that could break user code, but that isn't always followed and can put a huge burden on the code in some cases (like a re-architecturing of a subsystem, etc.). Also, deprecation warnings don't help someone who is trying to proactively determine if their existing code will work before upgrading. Right now, of course, you could point to the listing given in the release notes. However, often the trac ticket titles are (1) not very descriptive, (2) often poorly reflect what is actually in the patch, and (3) do not give any information about deprecations or other user-visible changes. On the other hand, reading all of the discussion on all of the trac tickets and then looking at all of the patches is clearly out of the question for most users to see what changed. Trac ticket titles and descriptions should be updated as a ticket evolves. Ideally http://trac.sagemath.org/sage_trac/query?group=componentmilestone=sage-4.4.2 should be a good summary of what happened. Of course, an alternative is to just make a special section of the commit message detailing possible compatibility issues, and then just automatically pull those out when making a release. If we did that, commit messages could be something like docstrings with sections for features added, compatibility issues, other user- visible changes, etc. Wow, that sounds like a lot of work too. But it could make Sage much more user-friendly. That would be cool too, actually ideal. - Robert -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
Re: [sage-devel] Re: Changelogs in SPKG.txt
On Wed, May 26, 2010 at 5:31 PM, kcrisman kcris...@gmail.com wrote: Not without having someone over your shoulder, which is why I still don't/can't use them. (Maybe Rob and Jason will finally teach me when they visit in June!). Sure. For a single patch, do hg qnew -f some_name # create a changeset hg qref -e # refresh the patch, including the commit message, as many times as you want hg qfinish tip # turn the patch into an actual commit I see. I guess for me I don't see the point of creating a new patch (again, for multiple strands I definitely see the point); I just wait until I'm done. Already my eyes glaze over ... :) But, like I said, Jason now has to promise to give me an in-person tutorial after fried clams! What's the point with a single patch? I use a combination of rollback and --no-commit for now. For creating good commit messages. Also, they're handy if you want to try something out and that you want to easily be able to revert. Again, hg_sage.rollback() and hg_sage.revert(options='--all') do that now for a single patch. In fact, I should really make hg_sage.revert_all() as an alias for that. Is there a problem with adding new commands like that, or should we only stick to ones which are actual HG commands? Go for it! I wrote hg_sage in a big hurry, and had always expected *YOU* were going to come along and greatly improve it, e.g., filling out all the capabilities, adding full support for queues, etc. William Random remark: One reason why HG alone is much harder than in Sage is that there is no tab completion of the various HG commands, no interactive verbose help accessible as easily with a ?, etc. That has saved me in hg_sage many, many times. One note--you don't have to type the whole command, just enough to make it unique. (Not as good as tab completion, but nice). That's actually quite interesting! Thanks; it could actually help me make the transition. - kcrisman -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org -- William Stein Professor of Mathematics University of Washington http://wstein.org -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
Re: [sage-devel] Re: Changelogs in SPKG.txt
On May 25, 2010, at 11:23 AM, kcrisman wrote: On May 25, 1:50 pm, William Stein wst...@gmail.com wrote: On Tue, May 25, 2010 at 10:41 AM, Robert Bradshaw rober...@math.washington.edu wrote: Hi all, I just had a new spkg (rightly) rejected because it didn't have a changelog entry in SPKG.txt , as specified by [1], Does anyone know why are we manually keeping a text changelog when the files under our control are already under revision control? Because of Abshoff Momentum? I can think of no other reason. I think this is silly. It makes more sense to reject a patch because the revision history comment is bad. Right now, with our dual system, the hg history comments can easily be bad, since one always has the SPKG.txt to back it up. So there are real negative consequences to the current confusing system. -- William Although I have to say that for someone looking to update an spkg, it is very helpful to have the big picture without scrolling through HG comments (esp. for HG-phobes), similarly to how it is quite useful to have the changelog.txt/HISTORY.txt file even though we have the HG log for Sage proper. It is much easier to look quickly to see what's been going on. $SAGE_ROOT/HISTORY.txt is woefully out of date. Hello folks, Sage 3.2.3 was released on January 5th, 2009. It is available at http://www.sagemath.org/download.html * About Sage (http://www.sagemath.org) Say, if one has a text editor open but has no interest in opening a terminal window and remembering the commands that get their HG working... and don't even get me started on trying to add HG from inside Sage to my PATH, that shouldn't be *required* to see what has happened in an spkg at the highest level. In fact, I'd say the solution is to start requiring better HG messages in *addition to* the spkg upgrades, just like has been happening slowly on the main patches. I'll also point out that someone said HG comments sometimes only show up one line at a time, or default display only one line, or something. So let's keep both, in the name of EVEN better documentation, but make it clear both should be good. Or am I the only one who finds SPKG.txt changes helpful? I think they are valuable, e.g. for recording license, build, maintainer, and build information. If people are averse to actually firing up hg to see what changed, we could always dump hg log to CHANGELOG.txt or something like that on packaging it up, rather than force users to put two separate, quality commit messages in. - Robert -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
Re: [sage-devel] Re: Changelogs in SPKG.txt
On Tue, May 25, 2010 at 11:23 AM, kcrisman kcris...@gmail.com wrote: On May 25, 1:50 pm, William Stein wst...@gmail.com wrote: On Tue, May 25, 2010 at 10:41 AM, Robert Bradshaw rober...@math.washington.edu wrote: Hi all, I just had a new spkg (rightly) rejected because it didn't have a changelog entry in SPKG.txt , as specified by [1], Does anyone know why are we manually keeping a text changelog when the files under our control are already under revision control? Because of Abshoff Momentum? I can think of no other reason. I think this is silly. It makes more sense to reject a patch because the revision history comment is bad. Right now, with our dual system, the hg history comments can easily be bad, since one always has the SPKG.txt to back it up. So there are real negative consequences to the current confusing system. -- William Although I have to say that for someone looking to update an spkg, it is very helpful to have the big picture without scrolling through HG comments (esp. for HG-phobes), similarly to how it is quite useful to have the changelog.txt/HISTORY.txt file even though we have the HG log for Sage proper. It is much easier to look quickly to see what's been going on. Say, if one has a text editor open but has no interest in opening a terminal window and remembering the commands that get their HG working... and don't even get me started on trying to add HG from inside Sage to my PATH, that shouldn't be *required* to see what has happened in an spkg at the highest level. In fact, I'd say the solution is to start requiring better HG messages in *addition to* the spkg upgrades, just like has been happening slowly on the main patches. I'll also point out that someone said HG comments sometimes only show up one line at a time, or default display only one line, or something. So let's keep both, in the name of EVEN better documentation, but make it clear both should be good. -1 If the problem is really that it is way too hard for you to remember sage -hg log then we can just put that line in SPKG.txt.E.g., == History == Please type sage -hg log for a log of all changes to this spkg. -- Or if that is too hard, then the sage -pkg script could just have a line sage -hg log LOG.txt in it... -- William Stein Professor of Mathematics University of Washington http://wstein.org -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
Re: [sage-devel] Re: Changelogs in SPKG.txt
On May 25, 2010, at 11:26 AM, Jason Grout wrote: On 5/25/10 12:41 PM, Robert Bradshaw wrote: Hi all, I just had a new spkg (rightly) rejected because it didn't have a changelog entry in SPKG.txt , as specified by [1], Does anyone know why are we manually keeping a text changelog when the files under our control are already under revision control? +1 to just making the commit messages more descriptive, as well as insisting that things like: Applying a patch; this patch should be removed when this package is updated because the patch has been applied upstream are documented in the SPKG.txt. This information is very useful, and probably better not in a changelog, where it will scroll off the bottom and be forgotten. I'd be up for a requirement that every patch we make should be listed in SPKG.txt, with a bit of explanation of why (and, when, if ever, it will become unnecessary), right next to the version information. That'd be helpful. - Robert -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
Re: [sage-devel] Re: Changelogs in SPKG.txt
On Tue, May 25, 2010 at 11:36 AM, Robert Bradshaw rober...@math.washington.edu wrote: On May 25, 2010, at 11:26 AM, Jason Grout wrote: On 5/25/10 12:41 PM, Robert Bradshaw wrote: Hi all, I just had a new spkg (rightly) rejected because it didn't have a changelog entry in SPKG.txt , as specified by [1], Does anyone know why are we manually keeping a text changelog when the files under our control are already under revision control? +1 to just making the commit messages more descriptive, as well as insisting that things like: Applying a patch; this patch should be removed when this package is updated because the patch has been applied upstream are documented in the SPKG.txt. This information is very useful, and probably better not in a changelog, where it will scroll off the bottom and be forgotten. I'd be up for a requirement that every patch we make should be listed in SPKG.txt, with a bit of explanation of why (and, when, if ever, it will become unnecessary), right next to the version information. That'd be helpful. Having info about patches is a good idea. I'm definitely not convinced SPKG.txt is the right place for it. I would install propose something *like* for every patch foo, having a file foo.wtf (or something) in patches/ that explains the patch. E.g., $ cd patches $ ls foo foo.patch foo.wtf The file foo.wtf would document why foo is done. Doing things like this will greatly increase the chances that docs are updated when they should be. This is similar to having docstrings in functions, instead of some other distant place. William -- William Stein Professor of Mathematics University of Washington http://wstein.org -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
Re: [sage-devel] Re: Changelogs in SPKG.txt
On May 25, 2010, at 11:50 AM, William Stein wrote: On Tue, May 25, 2010 at 11:36 AM, Robert Bradshaw rober...@math.washington.edu wrote: On May 25, 2010, at 11:26 AM, Jason Grout wrote: On 5/25/10 12:41 PM, Robert Bradshaw wrote: Hi all, I just had a new spkg (rightly) rejected because it didn't have a changelog entry in SPKG.txt , as specified by [1], Does anyone know why are we manually keeping a text changelog when the files under our control are already under revision control? +1 to just making the commit messages more descriptive, as well as insisting that things like: Applying a patch; this patch should be removed when this package is updated because the patch has been applied upstream are documented in the SPKG.txt. This information is very useful, and probably better not in a changelog, where it will scroll off the bottom and be forgotten. I'd be up for a requirement that every patch we make should be listed in SPKG.txt, with a bit of explanation of why (and, when, if ever, it will become unnecessary), right next to the version information. That'd be helpful. Having info about patches is a good idea. I'm definitely not convinced SPKG.txt is the right place for it. I would install propose something *like* for every patch foo, having a file foo.wtf (or something) in patches/ that explains the patch. E.g., $ cd patches $ ls foo foo.patch foo.wtf The file foo.wtf would document why foo is done. Doing things like this will greatly increase the chances that docs are updated when they should be. This is similar to having docstrings in functions, instead of some other distant place. I actually think that this will make it less likely to get looked at and appropriately cleaned up when versions are bumped. When I'd go to SPKG.txt to update the version information, I would see Version x.y.z, with these patches: ... and if there are notes about stuff being fixed upstream, I'd take care of it then, rather than having to look at each patch/about file individually. - Robert -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
Re: [sage-devel] Re: Changelogs in SPKG.txt
On Tue, May 25, 2010 at 12:02 PM, kcrisman kcris...@gmail.com wrote: changelog, where it will scroll off the bottom and be forgotten. I'd This is my main point, as well as for those who in the future will just be learning hg and find going the right directory etc. difficult. sage -hg log |more ?? As for HISTORY.txt, I don't understand why that isn't updated, since http://www.sagemath.org/mirror/src/changelogs/HISTORY.txt is just fine! -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org -- William Stein Professor of Mathematics University of Washington http://wstein.org -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
Re: [sage-devel] Re: Changelogs in SPKG.txt
On May 25, 2010, at 12:30 PM, Jason Grout jason-s...@creativetrax.com wrote: On 5/25/10 2:01 PM, Robert Bradshaw wrote: On May 25, 2010, at 11:50 AM, William Stein wrote: Having info about patches is a good idea. I'm definitely not convinced SPKG.txt is the right place for it. I would install propose something *like* for every patch foo, having a file foo.wtf (or something) in patches/ that explains the patch. E.g., $ cd patches $ ls foo foo.patch foo.wtf The file foo.wtf would document why foo is done. Doing things like this will greatly increase the chances that docs are updated when they should be. This is similar to having docstrings in functions, instead of some other distant place. I actually think that this will make it less likely to get looked at and appropriately cleaned up when versions are bumped. When I'd go to SPKG.txt to update the version information, I would see Version x.y.z, with these patches: ... and if there are notes about stuff being fixed upstream, I'd take care of it then, rather than having to look at each patch/about file individually. +1 to Robert's comments. Already, I don't ever make or use foo.patch files anymore because they are completely redundant and one more easily-forgotten step to make (they should be totally automated if they are required). Interesting If we added foo.why files (I think 'why' is a nicer extension :), that would just add a layer of complexity onto the updating process. So +1 to having all of the necessary instructions/metadata for updating an spkg right in the SPKG.txt file. Jason -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
Re: [sage-devel] Re: Changelogs in SPKG.txt
On May 25, 2010, at 12:30 PM, Jason Grout jason-s...@creativetrax.com wrote: On 5/25/10 2:01 PM, Robert Bradshaw wrote: On May 25, 2010, at 11:50 AM, William Stein wrote: Having info about patches is a good idea. I'm definitely not convinced SPKG.txt is the right place for it. I would install propose something *like* for every patch foo, having a file foo.wtf (or something) in patches/ that explains the patch. E.g., $ cd patches $ ls foo foo.patch foo.wtf The file foo.wtf would document why foo is done. Doing things like this will greatly increase the chances that docs are updated when they should be. This is similar to having docstrings in functions, instead of some other distant place. I actually think that this will make it less likely to get looked at and appropriately cleaned up when versions are bumped. When I'd go to SPKG.txt to update the version information, I would see Version x.y.z, with these patches: ... and if there are notes about stuff being fixed upstream, I'd take care of it then, rather than having to look at each patch/about file individually. +1 to Robert's comments. Already, I don't ever make or use foo.patch files anymore because they are completely redundant Interesting. If I remember correctly, you and I had a long discussion about those patch files, in which I was totally against them, and you argued for them. I think they are there now mostly because of you. I'm still against them and consider them a waste of time, just like the log in SPKG.txt. I am glad we now agree. and one more easily-forgotten step to make (they should be totally automated if they are required). If we added foo.why files (I think 'why' is a nicer extension :), that would just add a layer of complexity onto the updating process. So +1 to having all of the necessary instructions/metadata for updating an spkg right in the SPKG.txt file. There is a layer of complexity with either approach. One puts the instructions next to the file being patched, and one puts them in a separate file. It's just like putting docs in docstrings versus the Sage Constructions Guide. Jason -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
Re: [sage-devel] Re: Changelogs in SPKG.txt
On May 25, 2010, at 12:35 PM, kcrisman wrote: On May 25, 3:05 pm, William Stein wst...@gmail.com wrote: On Tue, May 25, 2010 at 12:02 PM, kcrisman kcris...@gmail.com wrote: changelog, where it will scroll off the bottom and be forgotten. I'd This is my main point, as well as for those who in the future will just be learning hg and find going the right directory etc. difficult. sage -hg log |more ?? Example: r-2.10.1.p1 Changes for .p0: hg log version changeset: 33:66f45042d4b4 user:David Kirkby david.kir...@onetel.net date:Tue Feb 16 20:54:03 2010 + summary: #8285 Update R's spkg-install to work on Solaris SPKG.txt version === r-2.10.1.p0 (David Kirkby, February 16th 2010) === * Several items all covered by #8285 * Added the undocumented option --without-ICU on Solaris, as that allows R to build - otherwise it fails. I suspect the ideal solution would be to add the ICU library from http://site.icu-project.org/ but this option does allow R to build. * Ensure SAGE64 will add the -m64 option on any platform, not just OS X as before. * Removed all references to the option --with-iconv=no, as R needs iconv now - it is no longer optional - see http://trac.sagemath.org/sage_trac/ticket/8191 * Implement a test for X on Solaris, as the previous test in spkg-install would always fail on Solaris, as Solaris lacks the header file checked for, despite the fact X support works fine. So now I check for a library on Solaris. Are you really suggesting that the commit message should be this long? Maybe they should be! Yes, I've got no problem with long commit messages, the more info the better (especially for obscure build files and configure scripts, where the changes are far from self documenting). There are some nice commit messages in the combinat code too. But I've never seen one that long in Sage, so at least there is a defacto rule that commit message are short short short. This is probably due to laziness more than anything, though for some things short messages are sufficient (e.g. the code should have enough documentation that #X - implemented Y may be sufficient). This sort of thing should be somewhere, and to be honest having it all in one place is very nice. I agree that other messages I've seen (both in SPKG.txt or commit messages) are less informative. And I reiterate that I recall somewhere a suggestion on sage-devel that commit messages should be one line long. Does no one else remember that? Or did it mean it should not have any carriage returns, but be as long as it wants (in which case this was not clear at all)? Only the first line shows up by default so it should be self-contained and concise (so that the listings are short). hg log -v will show long commit messages, and hg log -p will print out the patches as well. - Robert -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
Re: [sage-devel] Re: Changelogs in SPKG.txt
On Tue, May 25, 2010 at 12:56 PM, William A. Stein wst...@gmail.com wrote: Interesting. If I remember correctly, you and I had a long discussion about those patch files, in which I was totally against them, and you argued for them. I think they are there now mostly because of you. I'm still against them and consider them a waste of time, just like the log in SPKG.txt. I am glad we now agree. The one use they do have is that they allow you to view previous changes in the history without having to go back and download the original version of source file in order to see the differences. For example, if I wanted to see the state of a patch from a few versions ago, then I couldn't just look in the history, I'd have to go download the old version, find the file, and then run diff. --Mike -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
Re: [sage-devel] Re: Changelogs in SPKG.txt
On May 25, 2010, at 1:11 PM, Jason Grout wrote: On 5/25/10 2:56 PM, William A. Stein wrote: On May 25, 2010, at 12:30 PM, Jason Groutjason- s...@creativetrax.com wrote: On 5/25/10 2:01 PM, Robert Bradshaw wrote: On May 25, 2010, at 11:50 AM, William Stein wrote: Having info about patches is a good idea. I'm definitely not convinced SPKG.txt is the right place for it. I would install propose something *like* for every patch foo, having a file foo.wtf (or something) in patches/ that explains the patch. E.g., $ cd patches $ ls foo foo.patch foo.wtf The file foo.wtf would document why foo is done. Doing things like this will greatly increase the chances that docs are updated when they should be. This is similar to having docstrings in functions, instead of some other distant place. I actually think that this will make it less likely to get looked at and appropriately cleaned up when versions are bumped. When I'd go to SPKG.txt to update the version information, I would see Version x.y.z, with these patches: ... and if there are notes about stuff being fixed upstream, I'd take care of it then, rather than having to look at each patch/about file individually. +1 to Robert's comments. Already, I don't ever make or use foo.patch files anymore because they are completely redundant Interesting. If I remember correctly, you and I had a long discussion about those patch files, in which I was totally against them, and you argued for them. I think they are there now mostly because of you. I'm still against them and consider them a waste of time, just like the log in SPKG.txt. I am glad we now agree. Yes. I (and at least one other developer that refused to work on spkgs while we didn't use the standard distribute patch files method) argued that we should only have patch files, while you and Michael argued that we should only have the actual patched files. I've learned to deal with it now, and the three-way merging step makes the patch file largely unnecessary, though it's still an extra step and hassle to figure out exactly what file under src/ a patched file in patches/ corresponds to. If we just distributed patch files, that information would be contained in the patch, automating yet one more mindless tedious thing that takes time and resources. In fact, I believe we (you?) proposed adding a foo.file file as well that would just contain the file path to the file that foo patched. I worked up a shell script to automatically apply patched files based on that, but alas, the foo.file file never caught on... One difficulty is that there are some (if I remember) patches that are only done to some systems, but not others. I too would find it easier if the /patches directory were actual patches that were applied to / src automatically, but that's not a big sticking point for me. Was the problem that then patch became a dependancy? and one more easily-forgotten step to make (they should be totally automated if they are required). If we added foo.why files (I think 'why' is a nicer extension :), that would just add a layer of complexity onto the updating process. So +1 to having all of the necessary instructions/metadata for updating an spkg right in the SPKG.txt file. There is a layer of complexity with either approach. One puts the instructions next to the file being patched, and one puts them in a separate file. It's just like putting docs in docstrings versus the Sage Constructions Guide. I agree that both solutions require work. The layer of complexity I was talking about was the needing to open yet more files to make sure that you covered all of your bases in updating an spkg. It seems much easier to have all the necessary information in one place (easier to remember, find, and update). +1, especially for your example of applied upstream, not needed after version Z. - Robert -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
Re: [sage-devel] Re: Changelogs in SPKG.txt
On May 25, 2010, at 1:17 PM, Jason Grout wrote: On 5/25/10 3:07 PM, kcrisman wrote: There remains one additional problem. If we have been putting long information into SPKG.txt for a while with almost no information in the commit messages, getting rid of the SPKG.txt ones will leave a fairly large piece of their history mysterious at best. Solutions? Make the delete commit have the deleted changelog as the commit message? :) Or we can use queues to retroactively flesh out the history (though does this destroy timestamp information?) - Robert -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
