Hi Ævar,

On Tue, 13 Jul 2021, Ævar Arnfjörð Bjarmason wrote:

> [snip Ævar's suggestion to populate the manual page incrementally,
> interspersed with the commits that finalize implementing the respective
> functionality]
>
> I suggested this because I think it's much easier to read patches that
> are larger because they incrementally update docs or tests along with
> code, than smaller ones that are e.g. "add docs" followed by
> incrementally modifying the code.

My experience is the exact opposite of yours: shorter patches are easier
to read.

> That's because you can consider those atomically.

No, in a patch series you cannot consider any patch completely atomically.
Just like you don't consider any paragraph in any well-written book out of
context.

> If earlier doc changes refer to later code changes you're left jumping
> back & forth and wondering if the code you're reading that doesn't match
> the docs yet is a bug, or if it's solved in some later change you're now
> needing to mentally keep track of.

You only keep jumping back and forth when reviewing _patches_. We try to
do code review on this mailing list, which means that you have the code
locally and review it in the correct context. When you do that, a design
document is quite helpful. And the proposed manual page serves as such a
design document.

> Which is not some theoretical concern b.t.w., but exactly what I found
> myself doing when reading this series, hence the suggestion.

Part of the problem here seems to be that this patch series saw many
reviewer suggestions that forced it to increase in length. That was
probably not very helpful, after all.

The first iteration had 23 patches. Reviews forced it to grow to 28
patches in the second iteration. And that was still not enough, therefore
the third iteration consisted of 34 patches. And if you had had your way,
requiring Jeff to include a Linux backend in the same patch series, it
would have to increase in size again, and not just by a little.

This all sounds like we're truly falling into the trap of ignoring the
rule that the perfect is the enemy of the good.

I really would like to come back to a focused review that truly improves
the patches at hand, and avoids conflating the review of the actual patch
series with matters of personal taste (which is a recipe for
disagreement). After all, we are interested in getting this feature out to
users who need to work with very large worktrees, right? At least that's
my goal here.

Ciao,
Johannes