Junio C Hamano [off-list ref] 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.
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.
Thanks.
On Wed, Aug 2, 2017 at 9:28 AM, Junio C Hamano [off-list ref] wrote:
Junio C Hamano [off-list ref] writes:
quoted
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).
quoted
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.
On Wed, 2017-08-02 at 10:58 -0700, Stefan Beller wrote:
That may be either a contributors problem (lacking time or
motivation to go through a long document) or a problem with
the community.
I'm trying to avoid the former.
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.)
I could see quite some alternatives for this.
1. scripts
I guess the kernel community use some scripts to check if the patch
has the required style.[ref 1][ref 2]. I guess we could do something
similar. Like writing a script that checks the log messages for the
required format (sign-off, area etc.) and giving users advice about
how to fix the issue. After a all script test pass we could give
some advice to the user about how the patch needs to be sent.
To identify the set of commit messages that need to be checked we
could make the script accept a single parameter that specifies the
base of the branch. I'm not sure if this part could be automated.
2. Hooks
warning: this might be a little over thought.
1. Code all the checks as 'hooks scripts' that aren't samples.
Possibly scripts related to 'commit-msg'.
2. Place them in a 'hooks' directory under a new directory, possibly
named 'hook-checks'.
3. Inform the new contributor to re-initialize his git.git with
$ git init --template=/path/to/git/hook-checks
4. Rebasing their commits with 'rewording' each
Of course, this relies on the fact that he wouldn't have enabled
hooks in their git.git. In which case he would have to merge the
scripts with his own scripts.
I'm not pretty sure if they're feasible or not.
--
Kaartic