[PATCH] .github/PULL_REQUEST_TEMPLATE.md: add a note about single-commit PRs

[PATCH] .github/PULL_REQUEST_TEMPLATE.md: add a note about single-commit PRs

[Philippe Blain via GitGitGadget]

From: Philippe Blain <levraiphilippeblain@gmail.com>

Contributors using Gitgitgadget continue to send single-commit PRs with
their commit message text duplicated below the three-dash line,
increasing the signal-to-noise ratio for reviewers.

This is because Gitgitgadget copies the pull request description as an
in-patch commentary, for single-commit PRs, and _GitHub_ defaults to
prefilling the pull request description with the commit message, for
single-commit PRs (followed by the content of the pull request
template).

Add a note in the pull request template mentioning that for
single-commit PRs, the PR description should thus be kept empty, in the
hope that contributors read it and act on it.

This partly addresses:
https://github.com/gitgitgadget/gitgitgadget/issues/340

Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
    .github/PULL_REQUEST_TEMPLATE.md: add a note about single-commit PRs

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1665%2Fphil-blain%2Fempty-description-single-commit-prs-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1665/phil-blain/empty-description-single-commit-prs-v1
Pull-Request: https://github.com/git/git/pull/1665

 .github/PULL_REQUEST_TEMPLATE.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 952c7c3a2aa..65fa3a37173 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -4,4 +4,8 @@ a mailing list (git@vger.kernel.org) for code submissions, code reviews, and
 bug reports. Nevertheless, you can use GitGitGadget (https://gitgitgadget.github.io/)
 to conveniently send your Pull Requests commits to our mailing list.
 
+If you use Gitgitgadget for a single-commit pull request, please *leave the pull
+request description empty*: your commit message itself should describe your
+changes.
+
 Please read the "guidelines for contributing" linked above!

base-commit: bc7ee2e5e16f0d1e710ef8fab3db59ab11f2bbe7
-- 
gitgitgadget

Re: [PATCH] .github/PULL_REQUEST_TEMPLATE.md: add a note about single-commit PRs

[Junio C Hamano]

"Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:

> diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
> index 952c7c3a2aa..65fa3a37173 100644
> --- a/.github/PULL_REQUEST_TEMPLATE.md
> +++ b/.github/PULL_REQUEST_TEMPLATE.md
> @@ -4,4 +4,8 @@ a mailing list (git@vger.kernel.org) for code submissions, code reviews, and
>  bug reports. Nevertheless, you can use GitGitGadget (https://gitgitgadget.github.io/)
>  to conveniently send your Pull Requests commits to our mailing list.
>  
> +If you use Gitgitgadget for a single-commit pull request, please *leave the pull
> +request description empty*: your commit message itself should describe your
> +changes.
> +
>  Please read the "guidelines for contributing" linked above!

Making it easier for contributors to come up with the right output
is greatly appreciated.  I think "If you use Gitgitgadget for" ->
"For" is probably a good change, for two reasons (one, we do not
take pull request except for GGG gateway in the first place, and
two, PR messages being similar to cover letters, you do not want to
have a detailed PR message that (a) takes extra time to write, (b)
can duplicate what the you already have written, and (c) could
contradict what the commit log message says.

I wonder if such a rule can be also enforced at the GGG side?  It
apparently knows if it is dealing with a single-patch request or a
multi-patch series (as the types of messages this documentation
update tries to address are the only ones that get duplicates under
the three-dash line), and I've seen GGG complain on the contents of
the commit log message (e.g., "not signed off") so there is enough
support to inspect things in a PR and add instruction to the PR
discussion.  Unless the machinery GGG uses lack the ability to read
the PR message (unlike the commit log messages that it can read
apparently), it may be able to enforce that "for a single patch, PR
message should be empty" rule before the /submit instruction.  It
might make things even more helpful if it can notice the commit log
message is similar enough or superset of PR message and refrain from
inserting it after the three-dash line, but that might be asking too
much ;-)

Thanks for helping to improve the situation.

Will queue.

Re: [PATCH] .github/PULL_REQUEST_TEMPLATE.md: add a note about single-commit PRs

[Philippe Blain]

Hi Junio,

Le 2024-02-04 à 15:17, Junio C Hamano a écrit :
> "Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
>> diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
>> index 952c7c3a2aa..65fa3a37173 100644
>> --- a/.github/PULL_REQUEST_TEMPLATE.md
>> +++ b/.github/PULL_REQUEST_TEMPLATE.md
>> @@ -4,4 +4,8 @@ a mailing list (git@vger.kernel.org) for code submissions, code reviews, and
>>  bug reports. Nevertheless, you can use GitGitGadget (https://gitgitgadget.github.io/)
>>  to conveniently send your Pull Requests commits to our mailing list.
>>  
>> +If you use Gitgitgadget for a single-commit pull request, please *leave the pull
>> +request description empty*: your commit message itself should describe your
>> +changes.
>> +
>>  Please read the "guidelines for contributing" linked above!
> 
> Making it easier for contributors to come up with the right output
> is greatly appreciated.  I think "If you use Gitgitgadget for" ->
> "For" is probably a good change, for two reasons (one, we do not
> take pull request except for GGG gateway in the first place, and
> two, PR messages being similar to cover letters, you do not want to
> have a detailed PR message that (a) takes extra time to write, (b)
> can duplicate what the you already have written, and (c) could
> contradict what the commit log message says.

Good idea, I'll tweak that in v2.


> I wonder if such a rule can be also enforced at the GGG side?  It
> apparently knows if it is dealing with a single-patch request or a
> multi-patch series (as the types of messages this documentation
> update tries to address are the only ones that get duplicates under
> the three-dash line), and I've seen GGG complain on the contents of
> the commit log message (e.g., "not signed off") so there is enough
> support to inspect things in a PR and add instruction to the PR
> discussion.  Unless the machinery GGG uses lack the ability to read
> the PR message (unlike the commit log messages that it can read
> apparently), it may be able to enforce that "for a single patch, PR
> message should be empty" rule before the /submit instruction.  It
> might make things even more helpful if it can notice the commit log
> message is similar enough or superset of PR message and refrain from
> inserting it after the three-dash line, but that might be asking too
> much ;-)

Yes, it probably is possible, and Dscho suggested the same in [1] and [2].
I'll maybe get a crack at it eventually, but I hope in the meantime this
simple addition to the PR template will help a bit.

Thanks,

Philippe.

[1] https://github.com/gitgitgadget/gitgitgadget/issues/340#issuecomment-717782054
[2] https://github.com/gitgitgadget/gitgitgadget.github.io/pull/8#issuecomment-1133758832

[PATCH v2] .github/PULL_REQUEST_TEMPLATE.md: add a note about single-commit PRs

[Philippe Blain via GitGitGadget]

From: Philippe Blain <levraiphilippeblain@gmail.com>

Contributors using Gitgitgadget continue to send single-commit PRs with
their commit message text duplicated below the three-dash line,
increasing the signal-to-noise ratio for reviewers.

This is because Gitgitgadget copies the pull request description as an
in-patch commentary, for single-commit PRs, and _GitHub_ defaults to
prefilling the pull request description with the commit message, for
single-commit PRs (followed by the content of the pull request
template).

Add a note in the pull request template mentioning that for
single-commit PRs, the PR description should thus be kept empty, in the
hope that contributors read it and act on it.

This partly addresses:
https://github.com/gitgitgadget/gitgitgadget/issues/340

Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
    .github/PULL_REQUEST_TEMPLATE.md: add a note about single-commit PRs
    
    Changes since v1:
    
     * simplified the wording as suggested by Junio

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1665%2Fphil-blain%2Fempty-description-single-commit-prs-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1665/phil-blain/empty-description-single-commit-prs-v2
Pull-Request: https://github.com/git/git/pull/1665

Range-diff vs v1:

 1:  4786f84884a ! 1:  f719e11b1df .github/PULL_REQUEST_TEMPLATE.md: add a note about single-commit PRs
     @@ .github/PULL_REQUEST_TEMPLATE.md: a mailing list (git@vger.kernel.org) for code
       bug reports. Nevertheless, you can use GitGitGadget (https://gitgitgadget.github.io/)
       to conveniently send your Pull Requests commits to our mailing list.
       
     -+If you use Gitgitgadget for a single-commit pull request, please *leave the pull
     -+request description empty*: your commit message itself should describe your
     -+changes.
     ++For a single-commit pull request, please *leave the pull request description
     ++empty*: your commit message itself should describe your changes.
      +
       Please read the "guidelines for contributing" linked above!


 .github/PULL_REQUEST_TEMPLATE.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 952c7c3a2aa..37654cdfd7a 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -4,4 +4,7 @@ a mailing list (git@vger.kernel.org) for code submissions, code reviews, and
 bug reports. Nevertheless, you can use GitGitGadget (https://gitgitgadget.github.io/)
 to conveniently send your Pull Requests commits to our mailing list.
 
+For a single-commit pull request, please *leave the pull request description
+empty*: your commit message itself should describe your changes.
+
 Please read the "guidelines for contributing" linked above!

base-commit: bc7ee2e5e16f0d1e710ef8fab3db59ab11f2bbe7
-- 
gitgitgadget

Re: [PATCH] .github/PULL_REQUEST_TEMPLATE.md: add a note about single-commit PRs

[Junio C Hamano]

Philippe Blain <levraiphilippeblain@gmail.com> writes:

> Yes, it probably is possible, and Dscho suggested the same in [1] and [2].

Ah, great minds think alike, and Dscho's suggestion was made a few
years ago already.

> I'll maybe get a crack at it eventually, but I hope in the meantime this
> simple addition to the PR template will help a bit.

Perhaps.