Re: Train station analogy, was Re: [PATCH v3 00/15] [RFC] Upstreaming the Scalar command

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Tue, Sep 14 2021, Junio C Hamano wrote:

> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
>
>> Okay, let's try an analogy.
>>
>> Imagine that a person is asking for directions to the train station. And
>> the other person is replying by asking "did you know that this train
>> station was built in 1878? It is actually quite interesting a story...
>> [and then goes on to describe the history and what excites them about
>> it]". Now, the first person tries again to ask for directions, again does
>> not get an answer to that question, and is slowly starting to look at
>> their watch. The second person, being completely oblivious to all of this,
>> goes on with their wonderful story about the train station and its
>> cultural heritage. So the first person walks a bit further to ask a third
>> person, but the second person is not done yet and says "but you haven't
>> heard me out! That's disrespectful!".
>>
>> Just imagine for a minute how you would feel if you were the first person.
>>
>> And that is how I feel asking for reviews about the Scalar patch series
>> and then being forcefully dragged into that tangent about the build
>> process.
>
> At least to me, how this Makefile for Scalar should interact with
> the overall build process does not mesh well with the story about
> hwo direction to and history of the station are unrelated.  If we
> plan to start from contrib/ and eventually want to make it a part
> of the core Git (i.e. "git scalar <subcmd> ..." becomes just like
> "git bisect <subcmd> ..."), we would eventually need to see the
> recipe needed for including "bisect" and "scalar" work the same
> way, no?
>
> I am getting the impression that such a unified build process is
> Ævar wants to see at the end, I am not even sure if you do from
> the above "analogy".  Cool down a bit, perhaps?
>
> The following assumes that you share the goal of making "git
> scalar" just like "git bisect"---another first class citizen of
> Git toolbox, the user can choose to use it or the user may not
> have a need to interact with it, but it exists there by default
> and is not an opt-in add-on component.
>
> I would understand it if your plan is to convert to a unified
> build procedure at the very end of the upstreaming process, and
> not while you populate contrib/ with more and more scalar stuff,
> because the Makefile bits for the entire scalar, while not yet
> upstreamed, has already been written as a separate procedure and
> having to convert the whole thing upfront before you can start
> trickle parts would mean you need to (re)start the process.  And
> I would even be sympathetic if you felt it like a distraction.
>
> But at least I view it as a step that needs to happen sometime
> between now and at the end.  I do not yet have an opinion on
> which one is more pleasant, between (1) having to deal with a
> single Makefile that needs to be aware of two different locations
> *.[ch] lives in, and (2) having to deal with two Makefiles that
> duplicates definitions and risks them needlessly diverging.

For what it's worth what I had on top of this is not (1) or (2), but a
(0): I.e. there isn't a contrib/scalar anymore, I moved:

    contrib/scalar/scalar.c -> scalar
    contrib/scalar/scalar.txt -> Documentation/scalar.txt
    contrib/scalar/t9099-scalar.sh -> t/t9099-scalar.sh

We build, test, and otherwise check (e.g. "make check-docs") it by
default, what we don't do is install it unless you ask. You need to run:

    # Or any other install* target
    make install install-doc INSTALL_SCALAR=YesPlease

It could be be kept in contrib/scalar/ even with that sort of approach,
and it would still be simpler than the two-Makefile approach.

But just moving the code, tests and documentation where everything else
lives cuts down an all sorts of special cases, file globs in various
places (e.g. doc lints) will just work and won't need adjustment.

> I also would understand it if the reason why you want to keep the
> top-level Makefile as intact as possible because you sense a high
> probability that scalar will stay in contrib/ and even turn out
> to be a failure.  Keeping the build procedure separated certainly
> will keep it easier to yank it out later.  But I do not think
> such a case is quite likely.

For what it's worth the WIP patch(es) I have on top of it will probably
make such a thing even easier, not that removing it from the tree would
be much of a problem in either case. It's mostly a few lines added to
lists in various places in the Makfile.

If I were to clean this up properly most of the changes would be
teaching the Makefile that it can build N number of named top-level
"special" commands that get dropped into bin/, not just the "git" we
hardcode now.

If you're interested I could try to clean that up and send something on
top, but given the tense-ness of the discussion & unrelated but relevant
patch queue I've got outstanding wouldn't do so otherwise...