I used the developer's guide to get started with Sage about a year ago, and I still refer back to it from time to time. I'm enthusiastically in support of improving it!
Pros for mercurial queues: * quicker to get started * easier to understand (for some) * easy to transition from just reviewing patches to creating new patches Things I'd like to see: * recommendations for how to *not* loose work with queues: one pit I fell into (twice) was not understanding how to add entire new files to sage (you have to use 'hg add', if you don't, then 'hg qpop' will delete your file and not keep any record of it). A combination of 'hg diff', 'hg status', and 'cat .hg/patches/patch_name' can help users understand what mercurial is keeping track of. A new user should probably make a backup copy of files they've edited before they use qpop for the first time. * The order of references in http://www.sagemath.org/doc/developer/walk_through.html#more-on-queues should be reversed -- the mercurial reference for queues is written in the larger context of the entire mercurial repository system, which I (and other new developers probably) don't understand. In contrast, the Mozilla page seems written for the same purposes we have. The sage wiki page has some information, but looks like it's been forgotten for a while. * prominent recommendation to use 'hg qnew patch_name' BEFORE you make changes to the source code -- I think the current description just mentions making changes first, then using 'qnew -f'. Strangely, the Mozilla page recommends this too. This can get confusing if you're working on more than one patch at a time. * how to fold and split patches. I don't really know this myself, but it must be possible and surely is useful -- some description which I only just noticed is written on the wiki page. Also, is this what "cherry-picking" is? I don't understand the point of that section. * What to do when you upgrade sage and some patches don't apply: usually just one or two "hunks" fail, and I think a good workflow is first read the .rej file, then note that the "failed" patch is still "applied" -- not so intuitive, I think -- then use your human powers of reasoning to make the changes described in the failing hunk, and then qrefresh to update the patch to one that applies successfully. Then delete the .rej file (I think this happens automatically if you qpop and then qpush the updated patch, as described in my first point). Alternatively, you could qpop the patch and carefully, cleverly edit the patch file itself (e.g. change some line numbers) so that mercurial knows where/how to apply the failing hunks. * Building the entire sage library takes a long time, especially if you're a new developer using a less-than-fantastic machine. It would be great for someone to permanently record one or two ways to build just a part of the sage library. * How to make sure that new code is included in the Sage reference manual: It's relatively easy to figure out, but I had trouble with it and didn't see anything about it in the guide. * In the section "Reporting Bugs" http://www.sagemath.org/doc/developer/trac.html#reporting-bugs perhaps AskSage should be mentioned along side sage-devel and sage- support * conventions for naming patches on the Trac server might be useful: the one I've seen is "trac_ddddd_short_description.patch". * a trick I like using backticks for exporting patches to a file of the same name: "hg export tip > ~/`hgqtop`" Anyway, I hope these are useful and not too many suggestions :) -Niles p.s. cc me if you make a ticket for this :) -- 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
