== Some notes on bisecting a modified Firefox source base with Mercurial

Suppose, not hypothetically, that you maintain your own copy of the
Firefox master source (aka 'Nightly') with private modifications
on top of the Mozilla version. Of course you don't commit your
modifications, because that would lead to a huge tangle of merges
over time. Now suppose that Mozilla breaks something and you want
to use Mercurial bisection to find it.

The first thing you need is to figure out the last good version.  What I
do is I don't run my modified Firefox version directly out of the build
directory; instead I periodically make an install tarball and unpack it
elsewhere (and then keep the last few ones when I update it, so I can
revert in case of problems). Among other things this tarball copy has an
_application.ini_ file, which for my builds includes a _SourceStamp=_
value that gives the Mercurial commit identifier that the source was
built from.

.pn prewrap on

So we start the procedure by setting the range bounds:

>  hg bisect --good 606848e8adfc
>  hg bisect --bad tip

Since I'm carrying local modifications this will generally report
something like:

>  Testing changeset 192456:d2e7bd70dd95 (1663 changesets remaining, ~10 tests)
>  abort: uncommitted changes

So now I need to explicitly check out the named changeset. If I
skip this step Mercurial won't complain (and it will keep doing
future '_hg bisect_' operations without any extra complaints), but
what I'm actually doing all of the time is building the tip of my
repo. This is, as they say, not too useful. So:

>  hg checkout d2e7bd70dd95

This may print messages about merging changes in my changed files,
which is expected. In general Mercurial is smart enough to get
merging my changes in right unless something goes terribly wrong.
Afterwards I build and test and do either '_hg bisect --good_' or
'_hg bisect --bad_' followed by another '_hg checkout <ver>_'.

(If I remember I can use the '_-U_' argument to '_hg bisect_' so
it doesn't attempt the checkout and abort with an error, but enhh.
I actually think that having the error is handy because it reminds
me that I need extra magic and care.)

In some cases even the '_hg checkout_' may fail with the uncommitted
changes error message. In this case I need to drop my changes and
perhaps re-establish them later. The simple way is:

>  hg shelve
>  hg checkout ...

Perhaps I should routinely shelve all of my changes at the start of
the bisection process, unless I think some of them are important for
the testing I'm doing. It would cut down the hassle (and shelving
them at the start would make it completely easy to reapply them at
the end, since they'd be taken from tip and reapplied to tip).

After the whole bisection process is done, I need to cancel it and
return to the tip of the tree:

>  hg bisect --reset
>  hg checkout tip
>  # if required:
>  hg unshelve
>  # optional but customary:
>  hg pull -u

(This is the sort of notes that I write for myself because it prevents
me from having to reverse engineer all of this the next time around.)

=== Sidebar: Some related Mercurial bits I want to remember

The command to tell me what checkout I am on is '_hg summary_' aka
'_hg sum_'. '_hg status_' doesn't report this information; it's
just for *file* status. This correctly reports that the current
checkout hasn't changed when a '_hg bisect ..._' command aborts due
to uncommitted changes.

I don't think there's an easy command to report whether or not a
bisection is in progress. The best way to check is probably:
>  hg log -r 'bisect(current)'

If there's no output, there's no bisection in flight.

(I believe I've left bisections sitting around in the past by
omitting the '_hg bisect --reset_'. If I'm right, things like '_hg
pull -u_' and so on won't warn me that theoretically there is a
bisection running.)