[darcs-users] darcs patch: Rewrite "darcs trackdown" help.

[Eric Kow]

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 at 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.

> - "Given one argument, it treats it as a test command.  Given two arguments,\n"++
> - "the first is an initialization command with is run only once, and the\n"++
> - "second is the test command.\n"

> + "setpref').  A single argument is taken to be the test command.  Two\n" ++
> + "arguments are taken as an initialization command and a test command.\n" ++

And as a reward for reviewing patches I now learn that darcs trackdown
can take an initialisation argument

> + "In a temporary copy of the recorded working tree, the initialization\n" ++
> + "command is run just once.  Until the test succeeds, patches are\n" ++
> + "unapplied from the temporary working tree.  The `real' working tree is\n" ++
> + "not affected by this command.\n" ++
> + "\n" ++
> + "Examples:\n" ++
> + "\n" ++
> + "To find which patch made an autotools-based project fail to compile,\n" ++
> + "the initialization and test commands might be `./autogen.sh' and `make\n" ++
> + "all' respectively.\n" ++

> + "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

> + "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.

> + "There is no way to specify a subset of patches to test (that is,\n" ++
> + "--to-patch and --from-patch).  One workaround to avoid testing new\n" ++
> + "patches is to make a copy of the repository which lacks those patches\n" ++
> + "(e.g. with `darcs get --tag'), and run this command there.\n" ++

Thoughtful to mention.

> + "The order in which patches are unapplied is the reverse of the order\n" ++
> + "in which they are listed in the patch index.  This means that results\n" ++
> + "may differ after a `darcs optimize --reorder-patches', for example.\n"

-- 
Eric Kow <http://www.nltg.brighton.ac.uk/home/Eric.Kow>
PGP Key ID: 08AC04F9
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: Digital signature
URL: <http://lists.osuosl.org/pipermail/darcs-users/attachments/20091005/f7618b2e/attachment.pgp>