Re: [PATCH 2/2] doc: add another way to identify if a patch has been merged

From: Stefan Beller <sbeller@google.com>
Date: Aug 2, 2017, 17:58 UTC
Message-ID: <CAGZ79kYArf6R-vx1-Lm4X_ANLMrXc3VNd2aCQMnqq3J6y-s31Q@mail.gmail.com>
In-Reply-To: <xmqq60e6djcu.fsf@gitster.mtv.corp.google.com>

On Wed, Aug 2, 2017 at 9:28 AM, Junio C Hamano <gitster@pobox.com> wrote:

Show 9 quoted lines

> Junio C Hamano <gitster@pobox.com> writes:
>
>> I think the exchange Stefan cited was an example that we want to
>> have more of.  The contributor is indicating that, even though the
>> patch could be a drive-by patch by one-timer from whom we will never
>> hear again, it is not--the contributor is willing to learn the way
>> things are done here, and showing that it is worth _our_ time to
>> explain the things so that the future patches will take less effort
>> to accept on our side.

The example I cited contains two important parts that I considered.

> I tried to follow as best I could, here's my attempt (please advise).

    ok, I can help out as that conversation is very likely
    to deliver some impact.

> I'm a bit overwhelmed by the documentation for submitting a patch!

    That may be either a contributors problem (lacking time or
    motivation to go through a long document) or a problem with
    the community.

Here are my thoughts on the "problem with the community":

    We are using Git ourselves as a mere (content-)version-control-system
    What we really need is a community oriented workflow tool:
    Instead of writing a long-winded document on what you can
    do wrong in each contribution, we should have technical solutions
    that just present the single issue that needs addressing.

    For example when a contributor forgets to sign-off a patch,
    git-send-email could warn about the missing sign-off and
    present the rationale why our community needs sign-offs.

    As this is specific to our community, such that it cannot be
    baked into git-send-email, but rather we'd need a distributed
    configuration that is respected by various git commands.

We had the discussion on shipping a project config which is respected by git commands lately when discussing the .gitorder file that I proposed, and IIRC such a thing "doesn't quite fit into the broad picture of a version control system", so maybe we need another tooling in our community?

    Another example would be to show a hint/advice when
    commits with no or very short commit message are created.
    (also this is project specific, other communities do not expect
    commit messages as we do. So they would not want to utilize
    such an advice given).

Show 16 quoted lines

>>
>> Because we do not have a group of dedicated volunteers, it is done
>> by more experienced people around here but that can be done only
>> when they have time.  I view it as a more severe problem than any
>> documentation.  An abbreviated version of the documentation to
>> invite more new people means that we must be prepared to give more
>> high-touch onboarding help to them.
>
> Just to make sure there is no misunderstanding, I am not saying "do
> not update the doc to have an abbreviated version, because we will
> get more clueless newbies".  I am saying that it is not a good idea
> to add an abbreviated version _before_ we are prepared to handle
> more patches from new people that require high-touch help.
>
> If you are volunteering to coordinate and form the onboarding
> helpers group, that would be great.

I would not want to explain the same thing over and over again, but rather have a technical solution that explains the problem and solution once it is detected.

Coming up with a technical solution for each little quirk is not the hard part (e.g. grep for the sign off string, count lines of the commit message), but rather to put it in place. (How can I make sure that contributors run these small checker scripts? Currently I cannot.)

Thanks.