Re: [PATCH] improve doc heading for git-bisect

[Junio C Hamano <gitster@pobox.com>]

"Robert Anderson" <rwa000@gmail.com> writes:

> Err, then shouldn't it be removed from format-patch, rather than
> deleted manually every time format-patch is used?
> ...
> Then remove them from format-patch, IMO.

Everything Jakub said about the presentation is correct, and please take
hints by looking at patch postings by long timers on this list.

The output from the command is designed so that it _can_ be pasted into a
MUA edit buffer, but that's not the sole purpose.  It needs to resemble
mbox format for use of send-email, so when you paste into a context that
does not need some parts, it is your responsibility and common courtesy
for readers to remove them.

>>> Improve awkward heading in git-bisect documentation.
>> [...]
>>> -Avoiding to test a commit
>>> -~~~~~~~~~~~~~~~~~~~~~~~~~
>>> +Changing the revision to test
>>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>>
>>>  If in a middle of bisect session, you know what the bisect suggested
>>>  to try next is not a good one to test (e.g. the change the commit
>>
>> It is, I guess, better, but is it the best heading?  What we want to
>> describe here is how to deal when bisect stops on commit which cannot
>> be tested (e.g. project does not compile).
>
> I disagree. The situation you want to use this is more general than
> that.  Maybe you could test it, but doing so would be a waste of time
> because the commit is a trivial comment change.  In general, this
> simply what you need to know when you want to change the revision
> under test.

I agree with your reasoning.  Being able to test a different commit than
the suggested one is a useful feature of bisect, and we would want to help
readers by mentioning, as widely as possible, in what situations this mode
of operation that is described in the section is applicable.

Before your change, the title describes "One very typical situation in
which you may want to do what we teach in this section" (i.e. "I do not
want to test this commit"), the first paragraph describes the situation a
bit further, and then the remainder gives how.

After your change, the title describes "What we teach you how to do in
this section", the first paragraph of the section describes "Why you may
want to do such a thing".

A title is only one line.  It cannot afford to be too verbose.  People,
when they have problems, tend to skim documentation to see if there is
something applicable to their situation.  At least "Avoiding to test a
commit" should have worded "Avoiding to test the suggested commit" to draw
attention better from people in such a situation, and I agree with you
that "Changing the revision to test", "Testing a different revision",
etc. would work much better for that purpose.

But at the same time, I think the first paragraph "Why you may want to do
such a thing" should be strenghtened to cover wider scenario without going
to verbose, especially now the title has become even more bland --- it now
tells "what you would do" without hinting "why you might want to" anymore.
It currently talks only about what you said in your response "you could,
but you do not want to as you know it is a waste of time", and no other
scenarios you hinted in your response by saying "more general than that".

Making the first paragraph richer would help the readers who spotted the
(now better reworded) title to decide that the section indeed applies to
their situation.

Also, I think the section that follows this part should be part of this
section.  Either you reset to a specific commit, or you use "bisect skip"
to pick another one for you.  Both are solutions to the same problem.