Re: [PATCH v2 1/1] commit: display advice hints when commit fails

From: Junio C Hamano <gitster@pobox.com>
Date: Dec 20, 2019, 18:34 UTC
Message-ID: <xmqqbls2alsb.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <20191220023125.GD227872@google.com>

Emily Shaffer <emilyshaffer@google.com> writes:

> Hm. I'm surprised to see this feedback come in the form of a local
> change when making the topic branch, rather than in a reply to the v1
> patch. What's the reasoning? (Or is this scissors patch intended to be
> the feedback?)

You haven't seen a suggestion in the form of counter-proposal?

Show 6 quoted lines

> I ask because out of all of us, it seems the Outreachy interns can
> benefit the most from advice on how and why to write their commit
> messages - that is, part of the point of an internship is to learn best
> practices and cultural norms in addition to coding practice. (Plus, I
> find being asked to rewrite a commit message tends to force me to
> understand my own change even better than before.)

It's something Mentors can help doing (I do not necessarily have time for that myself), and you're welcome to use the "tenatively queued" version as an example.

> I'll go ahead and look through the changes to the commit message so I
> can learn what you're looking for too :)

Nice.

One thing you missed in your review of the "tentatively queued" version is the reversal of the order of presentation. Instead of starting with "I decided to do this" without explanation, give the picture of status quo to set the stage, explain what issue exists in the current behaviour, and then describe what approach was chosen to solve the issue.

> For me, I don't particularly see why we'd want to be rid of it - it sort
> of feels like "a picture is worth a thousand words" to include the
> actual use case in the commit message.

Output coming from commands and/or options that are used only in a bit more advanced workflow and the ones that are rarely seen, I do agree that showing example is a good way to illustrate exactly what you are talking about.

On the other hand, for behaviour of basic local commands like "git add", "git commit", "git diff", ..., I do not necessarily agree, as these should be obvious and clear to all the intended audiences, which would be "anybody who has used Git for say more than two weeks.