Re: [PATCH] Fixed --shallow-since generating descendant borders

"Samo Pogačnik via GitGitGadget" [off-list ref] writes:

Subject: Re: [PATCH] Fixed --shallow-since generating descendant borders

A patch title wants maximum information density, and "Fixed" is a
vague verb in that context, as it does not tell what existing
behaviour was wrong or what is the right alternative behaviour.

As "git log --oneline --no-merges" can show, our patches typically
begins with the area the change pertains to plus a colon.  "git log
--oneline shallow.c" (which is the file this patch touches) shows a
handful ones that are prefixed with "shallow:".

What to write after the "<area>:" prefix for this patch, I am not
sure, as the body of the proposed log message does not discuss the
bad effect of the suboptimal or wrong (I cannot even tell which one
from the proposed log message) behaviour.

From: =?UTF-8?q?Samo=20Poga=C4=8Dnik?= <redacted>

When shallow cloning based on a date, it happens that a list
of commits is received, where some of the list border commits
actually descend one from another. In such cases borders need
to be expanded by additional parents and excluding the child
as border.

Missing from the above description are

 - received by whom?

 - the reason why they want such a list is to do what?

 - when there are multiple borders that can be "expanded", and if
   you leave it unexpanded (i.e., the behaviour of the current code)
   what happens and why is it bad?  Is it breaking bad (e.g., clone
   would be aborted, the resulting cloned repository does not pass
   fsck), or is it suboptimal bad (e.g., we told the command that we
   do not want commits older than date X, but we end up having more
   commits)?

 - what is the cost of computing the "expansion", relative to the
   above "badness"?  Fixing a breaking bad behaviour can of course
   afford to spend more cycles than a suboptimal bad behaviour.

The usual way to compose a log message of this project is to

 - Give an observation on how the current system works in the
   present tense (so no need to say "Currently X is Y", or
   "Previously X was Y" to describe the state before your change;
   just "X is Y" is enough), and discuss what you perceive as a
   problem in it.

 - Propose a solution (optional---often, problem description
   trivially leads to an obvious solution in reader's minds).

 - Give commands to somebody editing the codebase to "make it so",
   instead of saying "This commit does X".

in this order.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2107%2Fspog%2Ffix-shallow-since-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2107/spog/fix-shallow-since-v1
Pull-Request: https://github.com/git/git/pull/2107

 shallow.c | 35 ++++++++++++++++++++++++++++++++---
 1 file changed, 32 insertions(+), 3 deletions(-)

We'd want to protect this change from other people accidentally
breaking it in the future, and the best practice we have is to write
a test to observe end-user visible behaviour.  The whole helper
function being touched by the patch came in the 27-patch series
merged at a460ea4a (Merge branch 'nd/shallow-deepen', 2016-10-10),
and it seems to have added to t5500-fetch-pack.sh to cover the
"--shallow-since" feature.  Perhaps this should add a few tests to
demonstrate existing "breakage" (i.e., a "test_expect_success" test
that would fail without the change in the patch to shallow.c we see
below, and would succeed when the patch to shallow.c is applied).

Thanks.