Re: What's cooking in git.git (Aug 2022, #02; Fri, 5)

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 20, 2022, 00:18 UTC
Message-ID: <xmqqo7wfix7p.fsf@gitster.g>
In-Reply-To: <CAPig+cRp4N=6EktoisKAH09aVAPkPgZfHJYcB5pJFJ-CUpBHFA@mail.gmail.com>

Eric Sunshine <sunshine@sunshineco.com> writes:

Show 14 quoted lines

> Unfortunately, I'm not going to be much help here since I don't grok
> "creation factor" well enough to put an explanation into words, even
> after having read the "algorithm" section multiple times[1]. The
> situation is further confused (at least to me) by the "algorithm"
> section in the `git range-diff` documentation stating that the "fudge
> factor ... should be smaller than 100%", yet your position in this
> discussion is that the creation factor can be greater than 100%.
>
> FOOTNOTES
>
> [1]: I likewise didn't understand it well enough when submitting[2]
> which added --creation-factor to `git format-patch`, which is why I
> punted at that time and simply referred the reader to the `git
> range-diff` documentation.

So it wasn't just me or other folks who were confused in the original discussion thread that lead to

https://lore.kernel.org/git/xmqqa68nlfiz.fsf@gitster.g/

where I said

    ... The former helps the readers guess what a reasonable value
    they want to specify is (e.g. "I can afford to dedicate yMB"), and
    the latter is essential for the readers to decide how exactly they
    express what they chose (e.g. "I want to give yMB, but it is
    measured in bytes, so I'll write y * 10^20 here").  We need both.

    So _after_ they decide that 1.20 is the right number they want to
    give to --creation-factor, the knowledge that the number is
    expressed as percent does help them to write --creation-factor=120
    correctly (not --creation-factor=1.20).

    But for readers to come up with the number 1.20, there needs a
    better explanation of what the number means in the first place.  "Go
    read the algorithm section" is better than having nothing there, but
    we should be able to do better by having a simple-to-understand
    single paragraph description.

i.e. out of the current documentation, it is hard for readers to extract information they need to decide what value they want to specify. The part of it that talks about <percent> may tell them to spell "120" when they want to specify 1.20, but that is not all that helpful when they do not know what criteria they want to use to choose between 0.60 and 1.20 in the first place X-<.