Subject: Re: What's cooking in git.git (Jun 2021, #07; Wed, 30)

From: Ævar Arnfjörð Bjarmason <[email-masked]>
Date: Fri, 02 Jul 2021 14:18:40 +0200

On Thu, Jul 01 2021, Junio C Hamano wrote:

> Ævar Arnfjörð Bjarmason <[email-masked]> writes:
>
>> And:
>>
>>>  - Makefile: remove an out-of-date comment
>>>  - Makefile: stop hardcoding {command,config}-list.h
>>>  - Makefile: mark "check" target as .PHONY
>>
>> https://lore.kernel.org/git/[email-masked]/
>>
>> But you re-combined them. If it makes things easier for you I'm all for
>> it, but it seems better to me keep them split if that mean that some
>> parts can advance faster, and thus make the rest easier to review.
>
> I am all for that reasoning, but in this case (and other topics that
> I "combined", as well), one had textual dependencies on the other,
> and didn't make sense to split them into two, as neither part can
> advance without affecting the other, if I recall correctly.

Yes, they can't be advanced separately, one depends on the other in
turn. I'm suggesting that the parts that go earlier in the sequence
could advance before the later parts.

I.e. the whole hook topic is a big chunk that needs careful review, but
e.g. the relatively trivial Makefile topic could hopefully advance
fairly fast to "master", followed by the easily understood hook-list.h
topic.

The result would be peeling the first 6 commits off
ab/config-based-hooks-base, leaving a smaller set of commits for
reviewers of the "meaty" part of ab/config-based-hooks-base to focus on.

I started doing it this way because of your comments that I tended to
produce fairl long-winded topics. Often e.g. I'll find a bug, only to
discover that we don't test anything in that area. I thought that by
putting trivial cleanups, tests etc. first some of the "prep" work could
graduate early, leaving the more complex for later.

But perhaps that's not something you'd like to see. I'm still trying to
get a feel for if/how you'd like to split certain things.

One alternative in general (although not so much with the
ab/config-based-hooks-base topic) would be to simply withhold some of
the later parts locally. I've got several topics outstanding that are in
that state, the real "meaty" part hasn't landed on-list yet.

That has the advantage of having smaller and more incremental parts
on-list for review, but at the drawback that those earlier topics often
seem like a "bridge to nohere". E.g. my "handle_stdin_line" topic[1] is
one such topic. I found an existing in-tree user for it, but the real
thing I wanted it for still hasn't materialized.

>>> * ab/doc-retire-alice-bob (2021-06-16) 6 commits
>>>  - pack-protocol doc: use "www-data" in place of "alice"
>>>  - doc: replace "alice" and "bob" with "jdoe" and "msmith"
>>>  - fast-import doc: change "bob" in an example to "file.txt"
>>>  - daemon doc + code comments: reword "alice" example
>>>  - gitcvs-migration doc: replace "alice" and "bob" with "you" and "www-data"
>>>  - gittutorial doc: replace "alice" and "bob" with "you" and "www-data"
>>
>> Having re-read the discussion now I don't know if there's anything
>> outstanding to change about this series. It's gotten a lot of attention
>> so far, so it's more of a matter of if you're willing to take this sort
>> of documentation change or not.
>
> I actually do agree with the objection that www-data is a contrived
> thing to use in the examples, not because the user www-data is
> distro specific, but because it involves one physical human user
> acting on two accounts, instead of two human users interacting with
> each other.

The www-thing is arbitrary, and I can change that bit, but what do you
think of what I mentioned at the end of [2], i.e.:

    [...] the purposes of the example in the guide replacing Alice & Bob
    with You & another version of you removes a lot of potential
    confusion, we don't need to cover permissions, the other user doing
    unexpected things like non-ff updates, pruning branches you may have
    relied on through the --local clone etc.
    
    It's implicit that both "users" are you, so we only have to discuss the
    point of the actual example, how to pull and push between two different
    repos, the "different users" in this case was always a distraction.

I do think it makes things simpler in that sense, i.e. aside from "alice
and bob" if we start talking about two human users on the same system
the reader we'll need to be more guarded about describing repository
interactions, because we're acting on remote data that the reader might
correctly assume is changing concurrently outside of their control.

Whereas the real point of that example is to demonstrate how one user
might push and pull between two repositories under their control, so
using an example that assumes one user implicitly side-steps any such
discussion of permissions, data races etc.

1. https://lore.kernel.org/git/[email-masked]/
2. https://lore.kernel.org/git/[email-masked]/