[PATCH 1/2] doc: fix small issues in SubmittingPatches

[PATCH 1/2] doc: fix small issues in SubmittingPatches

[Kaartic Sivaraam]

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 Documentation/SubmittingPatches | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 558d465b6..9d0dab08d 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -293,7 +293,7 @@ then you just add a line saying
 
         Signed-off-by: Random J Developer <random@developer.example.org>
 
-This line can be automatically added by Git if you run the git-commit
+This line can be automatically added by Git if you run the 'git commit'
 command with the -s option.
 
 Notice that you can place your own Signed-off-by: line when
@@ -366,7 +366,7 @@ suggests to the contributors:
      spend their time to improve your patch.  Go back to step (2).
 
  (4) The list forms consensus that the last round of your patch is
-     good.  Send it to the maintainer and cc the list.
+     good. Send it to the maintainer and cc the list.
 
  (5) A topic branch is created with the patch and is merged to 'next',
      and cooked further and eventually graduates to 'master'.
-- 
2.14.0.rc1.434.g6eded367a

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

[Kaartic Sivaraam]

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 I'm not sure if the first one (pull --rebase) is still
 required and hence leaving it as such. Let me know if it
 could be removed.

 Documentation/SubmittingPatches | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 9d0dab08d..a800e54a7 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -386,6 +386,10 @@ Know the status of your patch after submission
   tell you if your patch is merged in pu if you rebase on top of
   master).
 
+* If you made your change in a separate branch (<branch>) you can use
+  'git cherry master <branch>' to see if the change has been merged
+  into master.
+
 * Read the Git mailing list, the maintainer regularly posts messages
   entitled "What's cooking in git.git" and "What's in git.git" giving
   the status of various proposed changes.
-- 
2.14.0.rc1.434.g6eded367a

Re: [PATCH 1/2] doc: fix small issues in SubmittingPatches

[Philip Oakley]

From: "Kaartic Sivaraam" <kaarticsivaraam91196@gmail.com>

minor nit: It's nice, for these single character changes, to give a clue in 
the commit message as to what to look for.

E.g.

Quote the command, and remove duplicated space character

--
Philip.

> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
> ---
> Documentation/SubmittingPatches | 4 ++--
> 1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/SubmittingPatches 
> b/Documentation/SubmittingPatches
> index 558d465b6..9d0dab08d 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -293,7 +293,7 @@ then you just add a line saying
>
>         Signed-off-by: Random J Developer <random@developer.example.org>
>
> -This line can be automatically added by Git if you run the git-commit
> +This line can be automatically added by Git if you run the 'git commit'
> command with the -s option.
>
> Notice that you can place your own Signed-off-by: line when
> @@ -366,7 +366,7 @@ suggests to the contributors:
>      spend their time to improve your patch.  Go back to step (2).
>
>  (4) The list forms consensus that the last round of your patch is
> -     good.  Send it to the maintainer and cc the list.
> +     good. Send it to the maintainer and cc the list.
>
>  (5) A topic branch is created with the patch and is merged to 'next',
>      and cooked further and eventually graduates to 'master'.
> -- 
> 2.14.0.rc1.434.g6eded367a
> 

Re: [PATCH 1/2] doc: fix small issues in SubmittingPatches

[Kaartic Sivaraam]

On Sun, 2017-07-30 at 15:49 +0100, Philip Oakley wrote:
> From: "Kaartic Sivaraam" <kaarticsivaraam91196@gmail.com>
> 
> minor nit: It's nice, for these single character changes, to give a clue in 
> the commit message as to what to look for.
> 
> E.g.
> 
> Quote the command, and remove duplicated space character
> 
Fixed it. Will remember this in future. :)

-- 
Kaartic

[PATCH 1/2] doc: fix small issues in SubmittingPatches

[Kaartic Sivaraam]

Replace the dashed version of a command with undashed
version and quote it.

Further, remove duplicated space character.

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 Documentation/SubmittingPatches | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 558d465b6..9d0dab08d 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -293,7 +293,7 @@ then you just add a line saying
 
         Signed-off-by: Random J Developer <random@developer.example.org>
 
-This line can be automatically added by Git if you run the git-commit
+This line can be automatically added by Git if you run the 'git commit'
 command with the -s option.
 
 Notice that you can place your own Signed-off-by: line when
@@ -366,7 +366,7 @@ suggests to the contributors:
      spend their time to improve your patch.  Go back to step (2).
 
  (4) The list forms consensus that the last round of your patch is
-     good.  Send it to the maintainer and cc the list.
+     good. Send it to the maintainer and cc the list.
 
  (5) A topic branch is created with the patch and is merged to 'next',
      and cooked further and eventually graduates to 'master'.
-- 
2.14.0.rc1.434.g6eded367a

Re: [PATCH 1/2] doc: fix small issues in SubmittingPatches

[Stefan Beller]

On Sun, Jul 30, 2017 at 9:18 AM, Kaartic Sivaraam
<kaarticsivaraam91196@gmail.com> wrote:
> Replace the dashed version of a command with undashed
> version and quote it.

I like it, but similar as below, we'd want to go for
consistency.

>
> Further, remove duplicated space character.

https://en.wikipedia.org/wiki/Sentence_spacing
seems like a globally controversial thing. (I assumed
it was some sort of local dialect before researching
it properly)

I personally do not mind one way or another regarding
(double) spaces after a period, but I would think we'd
strive for consistency throughout the project.

>
> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
> ---
>  Documentation/SubmittingPatches | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index 558d465b6..9d0dab08d 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -293,7 +293,7 @@ then you just add a line saying
>
>          Signed-off-by: Random J Developer <random@developer.example.org>
>
> -This line can be automatically added by Git if you run the git-commit
> +This line can be automatically added by Git if you run the 'git commit'
>  command with the -s option.
>
>  Notice that you can place your own Signed-off-by: line when
> @@ -366,7 +366,7 @@ suggests to the contributors:
>       spend their time to improve your patch.  Go back to step (2).
>
>   (4) The list forms consensus that the last round of your patch is
> -     good.  Send it to the maintainer and cc the list.
> +     good. Send it to the maintainer and cc the list.
>
>   (5) A topic branch is created with the patch and is merged to 'next',
>       and cooked further and eventually graduates to 'master'.
> --
> 2.14.0.rc1.434.g6eded367a
>

Re: [PATCH 1/2] doc: fix small issues in SubmittingPatches

[Junio C Hamano]

Stefan Beller <sbeller@google.com> writes:

>> Further, remove duplicated space character.
>
> https://en.wikipedia.org/wiki/Sentence_spacing
> seems like a globally controversial thing. (I assumed
> it was some sort of local dialect before researching
> it properly)
>
> I personally do not mind one way or another regarding
> (double) spaces after a period, but I would think we'd
> strive for consistency throughout the project.

I am not sure if that is something we want to encourage newbies to
be doing.  Especially a patch like this (notice the double-space
before "Go back to..." in the pre-context) makes me feel it is
distracting without adding much "consistency" value.

And no, I am not suggesting a tree-wide sweep to make everything
consistent.

>>       spend their time to improve your patch.  Go back to step (2).
>>
>>   (4) The list forms consensus that the last round of your patch is
>> -     good.  Send it to the maintainer and cc the list.
>> +     good. Send it to the maintainer and cc the list.
>>
>>   (5) A topic branch is created with the patch and is merged to 'next',
>>       and cooked further and eventually graduates to 'master'.
>> --
>> 2.14.0.rc1.434.g6eded367a
>>

Re: [PATCH 1/2] doc: fix small issues in SubmittingPatches

[Kaartic Sivaraam]

On Mon, 2017-07-31 at 13:23 -0700, Stefan Beller wrote:
> On Sun, Jul 30, 2017 at 9:18 AM, Kaartic Sivaraam
> <kaarticsivaraam91196@gmail.com> wrote:
> > Replace the dashed version of a command with undashed
> > version and quote it.
> 
> I like it, but similar as below, we'd want to go for
> consistency.
> 
I assume you mean the consistency in quoting i.e., you're expecting the
patch to use (") instead of (') for quoting. Correct me, if I'm wrong.

> > 
> > Further, remove duplicated space character.
> 
> https://en.wikipedia.org/wiki/Sentence_spacing
> seems like a globally controversial thing. (I assumed
> it was some sort of local dialect before researching
> it properly)
> 
Man, I had no idea about people using two spaces after period.

> I personally do not mind one way or another regarding
> (double) spaces after a period, but I would think we'd
> strive for consistency throughout the project.
> 
Consistency is crucial. I'll just remove that part of the patch.

-- 
Kaartic

Re: [PATCH 1/2] doc: fix small issues in SubmittingPatches

[Stefan Beller]

On Tue, Aug 1, 2017 at 8:59 AM, Kaartic Sivaraam
<kaarticsivaraam91196@gmail.com> wrote:
> On Mon, 2017-07-31 at 13:23 -0700, Stefan Beller wrote:
>> On Sun, Jul 30, 2017 at 9:18 AM, Kaartic Sivaraam
>> <kaarticsivaraam91196@gmail.com> wrote:
>> > Replace the dashed version of a command with undashed
>> > version and quote it.
>>
>> I like it, but similar as below, we'd want to go for
>> consistency.
>>
> I assume you mean the consistency in quoting i.e., you're expecting the
> patch to use (") instead of (') for quoting. Correct me, if I'm wrong.

Actually I did not imply any expectation on the outcome, because I
do not know what the consistency end game looks like for this issue.

So maybe we'd want to go with the currently most used way?
(Are there only three? (a) with dash, (b) with single quotes and
(c) with double quotes?)

>> >
>> > Further, remove duplicated space character.
>>
>> https://en.wikipedia.org/wiki/Sentence_spacing
>> seems like a globally controversial thing. (I assumed
>> it was some sort of local dialect before researching
>> it properly)
>>
> Man, I had no idea about people using two spaces after period.
>
>> I personally do not mind one way or another regarding
>> (double) spaces after a period, but I would think we'd
>> strive for consistency throughout the project.
>>
> Consistency is crucial. I'll just remove that part of the patch.
>
> --
> Kaartic

Re: [RFC] The correct and consistent alternative to quote a command ?

[Kaartic Sivaraam]

On Tue, 2017-08-01 at 10:38 -0700, Stefan Beller wrote:
> On Tue, Aug 1, 2017 at 8:59 AM, Kaartic Sivaraam wrote:
> > I assume you mean the consistency in quoting i.e., you're expecting the
> > patch to use (") instead of (') for quoting. Correct me, if I'm wrong.
> 
> Actually I did not imply any expectation on the outcome, because I
> do not know what the consistency end game looks like for this issue.
> 
> So maybe we'd want to go with the currently most used way?
On scanning through Documentation/SubmittingPatches, I saw that most of
the commands were quoted using double quotes and chose to use it for
this patch. I'm not sure if it's the right one to use.

Changing the subject of this mail; hoping some one who has thoughts
about this would dive-in.

> (Are there only three? (a) with dash, (b) with single quotes and
> (c) with double quotes?)

-- 
Kaartic

Re: [RFC] The correct and consistent alternative to quote a command ?

[Junio C Hamano]

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

> On Tue, 2017-08-01 at 10:38 -0700, Stefan Beller wrote:
>> On Tue, Aug 1, 2017 at 8:59 AM, Kaartic Sivaraam wrote:
>> > I assume you mean the consistency in quoting i.e., you're expecting the
>> > patch to use (") instead of (') for quoting. Correct me, if I'm wrong.
>> 
>> Actually I did not imply any expectation on the outcome, because I
>> do not know what the consistency end game looks like for this issue.
>> 
>> So maybe we'd want to go with the currently most used way?
> On scanning through Documentation/SubmittingPatches, I saw that most of
> the commands were quoted using double quotes and chose to use it for
> this patch. I'm not sure if it's the right one to use.

After reading the patch before seeing the above, I also came to the
conclusion that the above is exactly what you are aiming at, and I
thought that was a reasonable thing to do.

Re: [RFC] The correct and consistent alternative to quote a command ?

[Stefan Beller]

On Wed, Aug 2, 2017 at 5:22 AM, Kaartic Sivaraam
<kaarticsivaraam91196@gmail.com> wrote:
> On Tue, 2017-08-01 at 10:38 -0700, Stefan Beller wrote:
>> On Tue, Aug 1, 2017 at 8:59 AM, Kaartic Sivaraam wrote:
>> > I assume you mean the consistency in quoting i.e., you're expecting the
>> > patch to use (") instead of (') for quoting. Correct me, if I'm wrong.
>>
>> Actually I did not imply any expectation on the outcome, because I
>> do not know what the consistency end game looks like for this issue.
>>
>> So maybe we'd want to go with the currently most used way?
> On scanning through Documentation/SubmittingPatches, I saw that most of
> the commands were quoted using double quotes and chose to use it for
> this patch. I'm not sure if it's the right one to use.

Thanks for checking. I think it is a reasonable thing to do then.

>
> Changing the subject of this mail; hoping some one who has thoughts
> about this would dive-in.
>
>> (Are there only three? (a) with dash, (b) with single quotes and
>> (c) with double quotes?)
>
> --
> Kaartic

Re: [RFC] The correct and consistent alternative to quote a command ?

[Kaartic Sivaraam]

On Wed, 2017-08-02 at 10:32 -0700, Stefan Beller wrote:
> Thanks for checking.
You're welcome. :)

-- 
Kaartic

[PATCH 1/2] doc: fix small issues in SubmittingPatches

[Kaartic Sivaraam]

Replace the dashed version of a command with undashed
version and quote it.

Use double quotes to quote a git command for consistency.

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 Documentation/SubmittingPatches | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 558d465b6..886fe3650 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -293,7 +293,7 @@ then you just add a line saying
 
         Signed-off-by: Random J Developer <random@developer.example.org>
 
-This line can be automatically added by Git if you run the git-commit
+This line can be automatically added by Git if you run the "git commit"
 command with the -s option.
 
 Notice that you can place your own Signed-off-by: line when
@@ -380,7 +380,7 @@ their trees themselves.
 Know the status of your patch after submission
 
 * You can use Git itself to find out when your patch is merged in
-  master. 'git pull --rebase' will automatically skip already-applied
+  master. "git pull --rebase" will automatically skip already-applied
   patches, and will let you know. This works only if you rebase on top
   of the branch in which your patch has been merged (i.e. it will not
   tell you if your patch is merged in pu if you rebase on top of
-- 
2.14.0.rc1.434.g6eded367a

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

[Kaartic Sivaraam]

Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
---
 Documentation/SubmittingPatches | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 886fe3650..7197709ee 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -386,6 +386,10 @@ Know the status of your patch after submission
   tell you if your patch is merged in pu if you rebase on top of
   master).
 
+* If you made your change in a separate branch (<branch>) you can use
+  "git cherry master <branch>" to see if the change has been merged
+  into master.
+
 * Read the Git mailing list, the maintainer regularly posts messages
   entitled "What's cooking in git.git" and "What's in git.git" giving
   the status of various proposed changes.
-- 
2.14.0.rc1.434.g6eded367a

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

[Stefan Beller]

On Tue, Aug 1, 2017 at 9:05 AM, Kaartic Sivaraam
<kaarticsivaraam91196@gmail.com> wrote:
> Signed-off-by: Kaartic Sivaraam <kaarticsivaraam91196@gmail.com>
> ---
>  Documentation/SubmittingPatches | 4 ++++
>  1 file changed, 4 insertions(+)
>
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index 886fe3650..7197709ee 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -386,6 +386,10 @@ Know the status of your patch after submission
>    tell you if your patch is merged in pu if you rebase on top of
>    master).
>
> +* If you made your change in a separate branch (<branch>) you can use
> +  "git cherry master <branch>" to see if the change has been merged
> +  into master.
> +
>  * Read the Git mailing list, the maintainer regularly posts messages
>    entitled "What's cooking in git.git" and "What's in git.git" giving
>    the status of various proposed changes.

Actually I am slightly negative on this one, because of
occurrences like [1].

Our SubmittingPatches is already considered *too long* for most people
who just want to drop a drive-by patch.

Adding more knowledge (which btw is about general git usage and not
specific to our development workflow; you'd find the same tip in the
kernel community).

I wonder if we need a document that describes workflows.
(Oh, look we have 'man gitworkflows'! I did not know)

So maybe we want to cut a lot of workflow related commendatory from
the SubmitingPatches and then encourage to read such man page?

[1 ]https://public-inbox.org/git/CA+dzEB=cDvp7ZS8x+p+U-5NbK3SNd0FPyj_wP=gvi8mJi6D2ag@mail.gmail.com/



> --
> 2.14.0.rc1.434.g6eded367a
>

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

[Kaartic Sivaraam]

On Tue, 2017-08-01 at 10:46 -0700, Stefan Beller wrote:
> Actually I am slightly negative on this one, because of
> occurrences like [1].
> 
> Our SubmittingPatches is already considered *too long* for most people
> who just want to drop a drive-by patch.
> 
> Adding more knowledge (which btw is about general git usage and not
> specific to our development workflow; you'd find the same tip in the
> kernel community).
> 
> I wonder if we need a document that describes workflows.
> (Oh, look we have 'man gitworkflows'! I did not know)
> 
> So maybe we want to cut a lot of workflow related commendatory from
> the SubmitingPatches and then encourage to read such man page?
> 
That's right. Maybe Documentation/SubmittingPatches needs a revamp to
be one-time contributor friendly? Maybe introducing a "gist" for people
who do not have the time to read the whole document, might be of help?

> [1 ]https://public-inbox.org/git/CA+dzEB=cDvp7ZS8x+p+U-5NbK3SNd0FPyj_wP=gvi8mJi6D2ag@mail.gmail.com/
> 
> 
> 
> > --
> > 2.14.0.rc1.434.g6eded367a
> > 

-- 
Kaartic

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

[Junio C Hamano]

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

> On Tue, 2017-08-01 at 10:46 -0700, Stefan Beller wrote:
>> Actually I am slightly negative on this one, because of
>> occurrences like [1].
>> 
>> Our SubmittingPatches is already considered *too long* for most people
>> who just want to drop a drive-by patch.
>> 
>> Adding more knowledge (which btw is about general git usage and not
>> specific to our development workflow; you'd find the same tip in the
>> kernel community).
>> 
>> I wonder if we need a document that describes workflows.
>> (Oh, look we have 'man gitworkflows'! I did not know)
>> 
>> So maybe we want to cut a lot of workflow related commendatory from
>> the SubmitingPatches and then encourage to read such man page?
>> 
> That's right. Maybe Documentation/SubmittingPatches needs a revamp to
> be one-time contributor friendly? Maybe introducing a "gist" for people
> who do not have the time to read the whole document, might be of help?

First of all, I do not think lack of one-time contributor is
something we should consider to be a problem.  Supporting new
contributors so that they will be involved more in the development
process is a lot more important issue.

A new contributor will get something wrong no matter what the
documentation says.  One-time contributor's intention is "I am
sending a patch this time, but I have no plan to get involved
further---I do not have time for this".  It ridiculous to ask for a
patch that adds an 's' to the end of a third-party-singular verb in
the present tense to be rerolled only because the title had an extra
full-stop at the end.  Practically, a patch like that by a "one time
contributor" will always have to be fixed before committing it.

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.

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

[Junio C Hamano]

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.
>
> 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.

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

[Stefan Beller]

On Wed, Aug 2, 2017 at 9:28 AM, Junio C Hamano <gitster@pobox.com> wrote:
> 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).

>>
>> 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.

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

[Kaartic Sivaraam]

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

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

[Kaartic Sivaraam]

On Wed, 2017-08-02 at 09:01 -0700, Junio C Hamano wrote:
> Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:
> 
> > On Tue, 2017-08-01 at 10:46 -0700, Stefan Beller wrote:
> > > So maybe we want to cut a lot of workflow related commendatory from
> > > the SubmitingPatches and then encourage to read such man page?
> > > 
> > 
> > That's right. Maybe Documentation/SubmittingPatches needs a revamp to
> > be one-time contributor friendly? Maybe introducing a "gist" for people
> > who do not have the time to read the whole document, might be of help?
> 
> First of all, I do not think lack of one-time contributor is
> something we should consider to be a problem.  Supporting new
> contributors so that they will be involved more in the development
> process is a lot more important issue.
> 
First of all, I would like to clear a little mis-interpretation here.
Though I used the phrase 'one-time contributor', I didn't want a gist
that targets only *those* people. I was thinking, in general, about
people who would like to contribute but find the documentation
overwhelming (an example might be the thread pointed out by Stefan). In
which case, they would want to check if their patch meets the *basic
criterias* and send it to the community hoping it would be accepted
with at least 75% probability.

I'll send a patch that tries to make 'Documentation/SubmittingPatches'
less overwhelming without losing much of it's content, some time soon.

> 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.
> 
I thought a *good* 'gist' would obviate that kind of effort. Let's see
if I could come up with something.

> 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.
> 
I think an abbrievated documentation whilst inviting new people
*should* obviate the onboarding help, saving everyone's time (win-win).

-- 
Kaartic

Re: [PATCH 1/2] doc: fix small issues in SubmittingPatches

[Philip Oakley]

From: "Stefan Beller" <sbeller@google.com>
>> Further, remove duplicated space character.
>
> https://en.wikipedia.org/wiki/Sentence_spacing
> seems like a globally controversial thing. (I assumed
> it was some sort of local dialect before researching
> it properly)
>
> I personally do not mind one way or another regarding
> (double) spaces after a period, but I would think we'd
> strive for consistency throughout the project.
>

The use of double spaces was a taught typing technique as recently as the 
early-mid 1980s when my wife did a UK university postgraduate secretarial 
course. This was just before PC word processing took off. It takes a long 
while for the old ways to die off!
--
Philip