Patch 27 Rewrite "darcs trackdown" help.

Title Rewrite "darcs trackdown" help.
Superseder Nosy List dagit, twb
Related Issues
Status obsoleted Assigned To twb

Created on 2009-10-31.12:35:24 by twb, last changed 2011-12-31.19:31:45 by kowey.

File name Status Uploaded Type Edit Remove
rewrite-_darcs-trackdown_-help_.dpatch twb, 2009-10-31.12:35:19 text/x-darcs-patch
unnamed twb, 2009-10-31.12:35:19 text/plain
See mailing list archives for discussion on individual patches.
msg9111 (view) Author: twb Date: 2009-10-31.12:35:19
Put this straight into "needs amendment" status and assign it to twb.

Eric Kow <kowey@darcs.net> writes:

> On Sat, Oct 03, 2009 at 18:32:32 +1000, Trent W.Buck wrote:
>> Sat Oct  3 18:23:08 EST 2009  Trent W. Buck <trentbuck@gmail.com>
>>   * Rewrite "darcs trackdown" help.
> I think my first comment may be grounds for some amendments.
> Could you have a look?
> I'll take this opportunity to mention
>   http://bugs.darcs.net/issue1208
> which asks for darcs trackdown --bisect
> David mentioned Delta Debugging, which sounds interesting, but we need
> somebody to give a more concrete idea on how this would fit into Darcs.
> Rewrite "darcs trackdown" help.
> -------------------------------
>> - "Trackdown tries to find the most recent version in the repository which\n"++
>> - "passes a test.  Given no arguments, it uses the default repository test.\n"++
>> + "The `darcs trackdown' command finds which patch made a test succeed.\n" ++
>> + "Without arguments, the default repository test is used (see `darcs\n" ++
> COMMENT: I think the old phrasing is more accurate that the new one.
> The new phrasing sounds like the patch you are referring to is one which
> is in the "keep" side of the history, whereas what I think you're saying
> is that darcs trackdown finds the one patch in the "discard" side of the
> history that you have to unpull to make the test pass.
> The old phrasing also talks about the "keep" side of the history, but it
> talks about the repository state, which makes sense.  I agree that
> talking about patches may be more useful, but then we also have to
> change perspectives.

I'll work on this some more next weekend.

I particularly want to avoid "most recent version", because it's not
standard terminology and obliges me to immediately explain the implied
ordering (instead of mentioning it later).

>> + "To benchmark successive versions of a project, the test command might\n" ++
>> + "be `make benchmarks; false'.  The `; false' causes the test to always\n" ++
>> + "fail, resulting in benchmarks for each version.\n" ++
> COMMENT: Is this really a reasonable thing to use darcs trackdown for?
> It may be useful to have a wiki page somewhere with darcs trackdown
> examples

IMO it is a abuse (not use) of trackdown; I kept mention of it only
because I thought you might object to its deletion ;-)

>> + "This command unapplies one patch at a time.  Bisecting (performing a\n" ++
>> + "binary search) over the set of patches would reduce the mean number of\n" ++
>> + "tests from O(n) to O(log n).  Bisection is not yet implemented.\n" ++
> COMMENT: Talking too much about bisection may confuse skimmers.  Maybe
> Bisection (performing a binary search) is not yet implemented.

+1; will do.

The "Limitations" section within trackdown and replace are mainly
grumbling, but I think they're also useful to say "hey, these are
problems we know about, and one day we intend to fix them."  IOW, full
msg10253 (view) Author: dagit Date: 2010-03-18.02:48:08

Do you think you'll pickup this work again anytime soon?  Looks like the 
last update was in October.

msg10261 (view) Author: twb Date: 2010-03-18.03:09:51
Jason Dagit wrote:
> Do you think you'll pickup this work again anytime soon?  Looks like
> the last update was in October.

I don't know.  I've been real slack working on Darcs lately, but OTOH
you have just bumped this back to the top of my IN tray :-)
msg14921 (view) Author: kowey Date: 2011-12-31.19:31:44
So, since this patch was submitted,

1. bisect was implemented
2. the reference to benchmarking was dropped (by "Clean up trackdown --
bisect documentation"?)
3. the documentation was moved out from the src to straight tex

So all that seems to remain is

4. rephrasing the documentation to clarify what 'recent version' is, and 
I think maybe our attempt at http://wiki.darcs.net/Using/Model may 
address that.

I say just let's just drop the issue.  Thanks, Trent! Apologies once 
more.  I think if we had been more responsive, we would still have a 
documentation czar :-(
Date User Action Args
2009-10-31 12:35:24twbcreate
2009-10-31 13:02:43twbsetstatus: needs-review -> followup-requested
assignedto: twb
2010-03-18 02:48:08dagitsetnosy: + dagit
messages: + msg10253
2010-03-18 03:09:51twbsetmessages: + msg10261
2011-12-31 19:31:45koweysetstatus: followup-requested -> obsoleted
messages: + msg14921