[PATCH v1] Configure Git contribution guidelines for github.com

[PATCH v1] Configure Git contribution guidelines for github.com

[Lars Schneider]

Many open source projects use github.com for their contribution process.
Although we mirror the Git core repository to github.com [1] we do not
use any other github.com service. This is unknown/unexpected to a
number of (potential) contributors and consequently they create Pull
Requests against our mirror with their contributions. These Pull
Requests become stall [2]. This is frustrating to them as they think we
ignore them and it is also unsatisfactory for us as we miss potential
code improvements and/or new contributors.

GitHub offers a way to notify Pull Request contributors about the
contribution guidelines for a project [3]. Let's make use of this!

[1] https://github.com/git/git
[2] https://github.com/git/git/pulls
[3] https://help.github.com/articles/creating-a-pull-request-template-for-your-repository/

Signed-off-by: Lars Schneider <larsxschneider@gmail.com>
---

Hi,

I am perfectly aware that adding a ".github" directory in the Git core
tree is ugly. However, I believe the benefits ("well informed new
contributors") outweigh the injury.

You can see how a github.com Pull Request creation window would like here:
https://github.com/larsxschneider/git/compare/master...larsxschneider-patch-1?quick_pull=1

I added a link that jumps to a part my GitMerge 2017 talk which explains
Git core contributions from my point view. Although I tried my best, the
presentation is not perfect and might not reflect the view of the Git
community. I wouldn't have a problem at all with removing the link.

I also did not break the lines in the .github/*.md files as I thought it
renders nicer on the github.com web interface. I am happy to change that,
too, though.

Cheers,
Lars


Notes:
    Base Ref: master
    Web-Diff: https://github.com/larsxschneider/git/commit/d859be5016
    Checkout: git fetch https://github.com/larsxschneider/git contrib-guide-v1 && git checkout d859be5016

 .github/CONTRIBUTING.md          | 10 ++++++++++
 .github/PULL_REQUEST_TEMPLATE.md |  3 +++
 2 files changed, 13 insertions(+)
 create mode 100644 .github/CONTRIBUTING.md
 create mode 100644 .github/PULL_REQUEST_TEMPLATE.md

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
new file mode 100644
index 0000000000..8d01be6a71
--- /dev/null
+++ b/.github/CONTRIBUTING.md
@@ -0,0 +1,10 @@
+## Contributing to Git
+
+Thanks for taking the time to contribute to Git! Please be advised, that the Git community does not use github.com for their contributions. Instead, we use a [mailing list](http://public-inbox.org/git/) for code submissions, code reviews, and bug reports.
+
+Please [read the maintainer notes](http://repo.or.cz/w/git.git?a=blob_plain;f=MaintNotes;hb=todo) to learn how the Git
+project is managed, and how you can work with it. In addition, we highly recommend you to [read our submission guidelines](../Documentation/SubmittingPatches).
+
+If you prefer video, then [this talk](https://www.youtube.com/watch?v=Q7i_qQW__q4&feature=youtu.be&t=6m4s) might be useful to you as the presenter walks you through the contribution process by example.
+
+Your Git community
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000000..c737a64620
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,3 @@
+Thanks for taking the time to contribute to Git! Please be advised, that the Git community does not use github.com for their contributions. Instead, we use a mailing list for code submissions, code reviews, and bug reports.
+
+Please read the "guidelines for contributing" linked above!

base-commit: 8d1b10321b20bd2a73a5b561cfc3cf2e8051b70b
--
2.13.0

Re: [PATCH v1] Configure Git contribution guidelines for github.com

[Ævar Arnfjörð Bjarmason]

On Fri, Jun 9, 2017 at 4:21 PM, Lars Schneider <larsxschneider@gmail.com> wrote:
> Many open source projects use github.com for their contribution process.
> Although we mirror the Git core repository to github.com [1] we do not
> use any other github.com service. This is unknown/unexpected to a
> number of (potential) contributors and consequently they create Pull
> Requests against our mirror with their contributions. These Pull
> Requests become stall [2]. This is frustrating to them as they think we
> ignore them and it is also unsatisfactory for us as we miss potential
> code improvements and/or new contributors.
>
> GitHub offers a way to notify Pull Request contributors about the
> contribution guidelines for a project [3]. Let's make use of this!
>
> [1] https://github.com/git/git
> [2] https://github.com/git/git/pulls
> [3] https://help.github.com/articles/creating-a-pull-request-template-for-your-repository/

It would be good to have some instructions, but instead of warning
people off we could just point them to submitgit.herokuapp.com

You can submit patches to this list using that, and if someone's
trying to submit a pull request they might be much happier using that.

E.g. here's one I made recently https://github.com/git/git/pull/362
and the resulting patch on the ML:
https://public-inbox.org/git/0102015c492e27c6-669f7ca8-e7c6-484f-9c5b-7cb9358ee966-000000@eu-west-1.amazonses.com/

>
> Signed-off-by: Lars Schneider <larsxschneider@gmail.com>
> ---
>
> Hi,
>
> I am perfectly aware that adding a ".github" directory in the Git core
> tree is ugly. However, I believe the benefits ("well informed new
> contributors") outweigh the injury.
>
> You can see how a github.com Pull Request creation window would like here:
> https://github.com/larsxschneider/git/compare/master...larsxschneider-patch-1?quick_pull=1
>
> I added a link that jumps to a part my GitMerge 2017 talk which explains
> Git core contributions from my point view. Although I tried my best, the
> presentation is not perfect and might not reflect the view of the Git
> community. I wouldn't have a problem at all with removing the link.
>
> I also did not break the lines in the .github/*.md files as I thought it
> renders nicer on the github.com web interface. I am happy to change that,
> too, though.
>
> Cheers,
> Lars
>
>
> Notes:
>     Base Ref: master
>     Web-Diff: https://github.com/larsxschneider/git/commit/d859be5016
>     Checkout: git fetch https://github.com/larsxschneider/git contrib-guide-v1 && git checkout d859be5016
>
>  .github/CONTRIBUTING.md          | 10 ++++++++++
>  .github/PULL_REQUEST_TEMPLATE.md |  3 +++
>  2 files changed, 13 insertions(+)
>  create mode 100644 .github/CONTRIBUTING.md
>  create mode 100644 .github/PULL_REQUEST_TEMPLATE.md
>
> diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
> new file mode 100644
> index 0000000000..8d01be6a71
> --- /dev/null
> +++ b/.github/CONTRIBUTING.md
> @@ -0,0 +1,10 @@
> +## Contributing to Git
> +
> +Thanks for taking the time to contribute to Git! Please be advised, that the Git community does not use github.com for their contributions. Instead, we use a [mailing list](http://public-inbox.org/git/) for code submissions, code reviews, and bug reports.
> +
> +Please [read the maintainer notes](http://repo.or.cz/w/git.git?a=blob_plain;f=MaintNotes;hb=todo) to learn how the Git
> +project is managed, and how you can work with it. In addition, we highly recommend you to [read our submission guidelines](../Documentation/SubmittingPatches).
> +
> +If you prefer video, then [this talk](https://www.youtube.com/watch?v=Q7i_qQW__q4&feature=youtu.be&t=6m4s) might be useful to you as the presenter walks you through the contribution process by example.
> +
> +Your Git community
> diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
> new file mode 100644
> index 0000000000..c737a64620
> --- /dev/null
> +++ b/.github/PULL_REQUEST_TEMPLATE.md
> @@ -0,0 +1,3 @@
> +Thanks for taking the time to contribute to Git! Please be advised, that the Git community does not use github.com for their contributions. Instead, we use a mailing list for code submissions, code reviews, and bug reports.
> +
> +Please read the "guidelines for contributing" linked above!
>
> base-commit: 8d1b10321b20bd2a73a5b561cfc3cf2e8051b70b
> --
> 2.13.0
>

Re: [PATCH v1] Configure Git contribution guidelines for github.com

[Lars Schneider]

> On 09 Jun 2017, at 18:18, Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote:
> 
> On Fri, Jun 9, 2017 at 4:21 PM, Lars Schneider <larsxschneider@gmail.com> wrote:
>> Many open source projects use github.com for their contribution process.
>> Although we mirror the Git core repository to github.com [1] we do not
>> use any other github.com service. This is unknown/unexpected to a
>> number of (potential) contributors and consequently they create Pull
>> Requests against our mirror with their contributions. These Pull
>> Requests become stall [2]. This is frustrating to them as they think we
>> ignore them and it is also unsatisfactory for us as we miss potential
>> code improvements and/or new contributors.
>> 
>> GitHub offers a way to notify Pull Request contributors about the
>> contribution guidelines for a project [3]. Let's make use of this!
>> 
>> [1] https://github.com/git/git
>> [2] https://github.com/git/git/pulls
>> [3] https://help.github.com/articles/creating-a-pull-request-template-for-your-repository/
> 
> It would be good to have some instructions, but instead of warning
> people off we could just point them to submitgit.herokuapp.com
> 
> You can submit patches to this list using that, and if someone's
> trying to submit a pull request they might be much happier using that.

Agreed! I wasn't sure if this solution is still active/maintained by Roberto!

- Lars

Re: [PATCH v1] Configure Git contribution guidelines for github.com

[Jonathan Nieder]

Hi,

Some mostly nitpicky initial thoughts.  Thanks for writing this.

Lars Schneider wrote:

> Many open source projects use github.com for their contribution process.
> Although we mirror the Git core repository to github.com [1] we do not
> use any other github.com service. This is unknown/unexpected to a
> number of (potential) contributors and consequently they create Pull
> Requests against our mirror with their contributions. These Pull
> Requests become stall [2]. This is frustrating to them as they think we
> ignore them and it is also unsatisfactory for us as we miss potential
> code improvements and/or new contributors.

I think this description could be more focused.  It's also not
self-contained --- e.g. the link to stalled pull requests is likely to
become stale over time, especially if GitHub gives us a way to disable
pull requests for the repository some day.

Could you summarize for me the motivation behind this patch?  Is it to
make Git more approachable, to avoid frustrating contributors, etc?

[...]
> I am perfectly aware that adding a ".github" directory in the Git core
> tree is ugly. However, I believe the benefits ("well informed new
> contributors") outweigh the injury.
> 
> You can see how a github.com Pull Request creation window would like here:
> https://github.com/larsxschneider/git/compare/master...larsxschneider-patch-1?quick_pull=1
> 
> I added a link that jumps to a part my GitMerge 2017 talk which explains
> Git core contributions from my point view. Although I tried my best, the
> presentation is not perfect and might not reflect the view of the Git
> community. I wouldn't have a problem at all with removing the link.
> 
> I also did not break the lines in the .github/*.md files as I thought it
> renders nicer on the github.com web interface. I am happy to change that,
> too, though.

This discussion is much clearer to me than the commit message.

I've found that often happens to me when writing patches, too.
Sometimes after proofreading I completely replace the initial
description that I wrote at commit time with what I came up later and
was going to put after the three-dash delimiter.

Would putting a PULL_REQUEST_TEMPLATE and CONTRIBUTING in the
top-level directory work?  If I'm reading
https://help.github.com/articles/setting-guidelines-for-repository-contributors/#adding-a-contributing-file
correctly then it seems to say the ".github/" prefix is optional.

I also find the long source lines hard to read.  Can you say more
about how broken lines render in the github.com web interface?  I
would have expected github's markdown renderer to behave like others
and cope with line wrapping.

Thanks and hope that helps,
Jonathan

Re: [PATCH v1] Configure Git contribution guidelines for github.com

[Junio C Hamano]

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

> On Fri, Jun 9, 2017 at 4:21 PM, Lars Schneider <larsxschneider@gmail.com> wrote:
> ...
>> I am perfectly aware that adding a ".github" directory in the Git core
>> tree is ugly. However, I believe the benefits ("well informed new
>> contributors") outweigh the injury.

I do not particulary see ".github" as an injury, and we already
carry .travis.yml in our tree ;-)

I agree with Ævar that mentioning the submitgit service would make
this even more helpful.

Re: [PATCH v1] Configure Git contribution guidelines for github.com

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> Lars Schneider wrote:
>
>> Many open source projects use github.com for their contribution process.
>> Although we mirror the Git core repository to github.com [1] we do not
>> use any other github.com service. This is unknown/unexpected to a
>> number of (potential) contributors and consequently they create Pull
>> Requests against our mirror with their contributions. These Pull
>> Requests become stall [2]. This is frustrating to them as they think we
>> ignore them and it is also unsatisfactory for us as we miss potential
>> code improvements and/or new contributors.
>
> I think this description could be more focused.  It's also not
> self-contained --- e.g. the link to stalled pull requests is likely to
> become stale over time, especially if GitHub gives us a way to disable
> pull requests for the repository some day.
>
> Could you summarize for me the motivation behind this patch?  Is it to
> make Git more approachable, to avoid frustrating contributors, etc?

I wonder if s/stall/stale/ is what Lars meant.  I think it is fair
to say that new contributors who are used to GitHub pull request
would find workflow with the mailing list unfamiliar, and from that
point of view, this is a step in a good direction.  Back when I
added GitHub as one of the publishing repositories, the best way to
convey this message available to us was to have a short comment on
the repository telling the readers not to throw a pull-request at
us.  If there are other mechanisms to do so more effectively, we
should use it.

Re: [PATCH v1] Configure Git contribution guidelines for github.com

[Jeff King]

On Fri, Jun 09, 2017 at 10:03:57AM -0700, Jonathan Nieder wrote:

> Would putting a PULL_REQUEST_TEMPLATE and CONTRIBUTING in the
> top-level directory work?  If I'm reading
> https://help.github.com/articles/setting-guidelines-for-repository-contributors/#adding-a-contributing-file
> correctly then it seems to say the ".github/" prefix is optional.

Yes, that should work. The ".github" option is there if you don't want
the cruft at your top-level. I don't mind CONTRIBUTING, but
PULL_REQUEST_TEMPLATE is kind of gross. :)

> I also find the long source lines hard to read.  Can you say more
> about how broken lines render in the github.com web interface?  I
> would have expected github's markdown renderer to behave like others
> and cope with line wrapping.

GitHub-Flavored Markdown treats newlines as a line break in the rendered
output, unlike the original Markdown implementation. I don't like that
myself, but it was done in the early days after seeing how many people
accidentally butchered their formatting because they expected the output
to look more like what they typed.

-Peff

Re: [PATCH v1] Configure Git contribution guidelines for github.com

[Philip Oakley]

From: "Lars Schneider" <larsxschneider@gmail.com>
> Many open source projects use github.com for their contribution process.
> Although we mirror the Git core repository to github.com [1] we do not
> use any other github.com service. This is unknown/unexpected to a
> number of (potential) contributors and consequently they create Pull
> Requests against our mirror with their contributions. These Pull
> Requests become stall [2]. This is frustrating to them as they think we
> ignore them and it is also unsatisfactory for us as we miss potential
> code improvements and/or new contributors.
>
> GitHub offers a way to notify Pull Request contributors about the
> contribution guidelines for a project [3]. Let's make use of this!
>
> [1] https://github.com/git/git
> [2] https://github.com/git/git/pulls
> [3] 
> https://help.github.com/articles/creating-a-pull-request-template-for-your-repository/
>
> Signed-off-by: Lars Schneider <larsxschneider@gmail.com>
> ---

I see there are currently 84 open PRs (13 in the last 14 days), so it is 
real.

I also see that the Issues page for git.git appears to be disabled, and will 
redirect to the pulls page.

Maybe the instructions should also be part of an Issues template which could 
reduce the potential number of PRs being created (but could create its own 
problems)


>
> Hi,
>
> I am perfectly aware that adding a ".github" directory in the Git core
> tree is ugly. However, I believe the benefits ("well informed new
> contributors") outweigh the injury.
>
> You can see how a github.com Pull Request creation window would like here:
> https://github.com/larsxschneider/git/compare/master...larsxschneider-patch-1?quick_pull=1
>
> I added a link that jumps to a part my GitMerge 2017 talk which explains
> Git core contributions from my point view. Although I tried my best, the
> presentation is not perfect and might not reflect the view of the Git
> community. I wouldn't have a problem at all with removing the link.
>
> I also did not break the lines in the .github/*.md files as I thought it
> renders nicer on the github.com web interface. I am happy to change that,
> too, though.
>
> Cheers,
> Lars
>
>
> Notes:
>    Base Ref: master
>    Web-Diff: https://github.com/larsxschneider/git/commit/d859be5016
>    Checkout: git fetch https://github.com/larsxschneider/git 
> contrib-guide-v1 && git checkout d859be5016
>
> .github/CONTRIBUTING.md          | 10 ++++++++++
> .github/PULL_REQUEST_TEMPLATE.md |  3 +++
> 2 files changed, 13 insertions(+)
> create mode 100644 .github/CONTRIBUTING.md
> create mode 100644 .github/PULL_REQUEST_TEMPLATE.md
>
> diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
> new file mode 100644
> index 0000000000..8d01be6a71
> --- /dev/null
> +++ b/.github/CONTRIBUTING.md
> @@ -0,0 +1,10 @@
> +## Contributing to Git
> +
> +Thanks for taking the time to contribute to Git! Please be advised, that 
> the Git community does not use github.com for their contributions. 
> Instead, we use a [mailing list](http://public-inbox.org/git/) for code 
> submissions, code reviews, and bug reports.

Isn't the mailing list git@vger.kernel.org, with an archive at 
http://public-inbox.org/git/ ?

> +
> +Please [read the maintainer 
> notes](http://repo.or.cz/w/git.git?a=blob_plain;f=MaintNotes;hb=todo) to 
> learn how the Git

Is using the repo.or.cz address deliberate as a way of highlighting that 
Github isn't the centre of the universe when accessing a DVCS repo?

Maybe the kernel.org repo should be first, or at least the alt-git.git repo 
at repo.or.cz listed in those same notes.

> +project is managed, and how you can work with it. In addition, we highly 
> recommend you to [read our submission 
> guidelines](../Documentation/SubmittingPatches).
> +
> +If you prefer video, then [this 
> talk](https://www.youtube.com/watch?v=Q7i_qQW__q4&feature=youtu.be&t=6m4s) 
> might be useful to you as the presenter walks you through the contribution 
> process by example.
> +
> +Your Git community
> diff --git a/.github/PULL_REQUEST_TEMPLATE.md 
> b/.github/PULL_REQUEST_TEMPLATE.md
> new file mode 100644
> index 0000000000..c737a64620
> --- /dev/null
> +++ b/.github/PULL_REQUEST_TEMPLATE.md
> @@ -0,0 +1,3 @@
> +Thanks for taking the time to contribute to Git! Please be advised, that 
> the Git community does not use github.com for their contributions. 
> Instead, we use a mailing list for code submissions, code reviews, and bug 
> reports.
> +
> +Please read the "guidelines for contributing" linked above!
>
> base-commit: 8d1b10321b20bd2a73a5b561cfc3cf2e8051b70b
> --
> 2.13.0
>
It's still a good idea though.
--
Philip 

Re: [PATCH v1] Configure Git contribution guidelines for github.com

[Junio C Hamano]

"Philip Oakley" <philipoakley@iee.org> writes:

> From: "Lars Schneider" <larsxschneider@gmail.com>
>> Many open source projects use github.com for their contribution process.
>> Although we mirror the Git core repository to github.com [1] we do not
>> use any other github.com service. This is unknown/unexpected to a
>> number of (potential) contributors and consequently they create Pull
>> Requests against our mirror with their contributions. These Pull
>> Requests become stall [2]. This is frustrating to them as they think we
>> ignore them and it is also unsatisfactory for us as we miss potential
>> code improvements and/or new contributors.
>>
>> GitHub offers a way to notify Pull Request contributors about the
>> contribution guidelines for a project [3]. Let's make use of this!
>>
>> [1] https://github.com/git/git
>> [2] https://github.com/git/git/pulls
>> [3]
>> https://help.github.com/articles/creating-a-pull-request-template-for-your-repository/
>>
>> Signed-off-by: Lars Schneider <larsxschneider@gmail.com>
>> ---
>
> I see there are currently 84 open PRs (13 in the last 14 days), so it
> is real.

Not so insignificant fraction of these are done purely for the
purpose of using submitgit, though.  In other words, if submitgit
were improved not to require a pull request against [1] (instead, it
could be pointed at a branch in a contributor's repository and do
the fromatting), these numbers will go down.

>> +Thanks for taking the time to contribute to Git! Please be advised,
>> that the Git community does not use github.com for their
>> contributions. Instead, we use a [mailing
>> list](http://public-inbox.org/git/) for code submissions, code
>> reviews, and bug reports.
>
> Isn't the mailing list git@vger.kernel.org, with an archive at
> http://public-inbox.org/git/ ?
>

I agree that I found the URL of the archive somewhat misleading for
those who want to contribute.  Giving the mailing list address makes
a lot more sense.  As suggested by Ævar in the thread, it would also
be good to suggest submitgit, given that the target audience of this
message was already prepared to throw a pull request at us.

>> +Please [read the maintainer
>> notes](http://repo.or.cz/w/git.git?a=blob_plain;f=MaintNotes;hb=todo)
>> to learn how the Git

Two minor issues here.

1. push the "read" outside [], i.e.

	Please read [<human readable name of the thing>](<URL for
	the thing>) to learn...

   as what is inside [] and what is inside () ought to be the moral
   equivalents.

2. the thing is not called "the maintainer notes"; it is called "A
   note from the maintainer". 

> Is using the repo.or.cz address deliberate as a way of highlighting
> that Github isn't the centre of the universe when accessing a DVCS
> repo?
>
> Maybe the kernel.org repo should be first, or at least the alt-git.git
> repo at repo.or.cz listed in those same notes.

I'd prefer [the k.org address](https://git.kernel.org/pub/scm/git/git.git/plain/MaintNotes?h=todo).

>> +project is managed, and how you can work with it. In addition, we
>> highly recommend you to [read our submission
>> guidelines](../Documentation/SubmittingPatches).

Again, push "read our" outside [].

Thanks.

Re: [PATCH v1] Configure Git contribution guidelines for github.com

[Lars Schneider]

> On 12 Jun 2017, at 17:52, Junio C Hamano <gitster@pobox.com> wrote:
> 
> "Philip Oakley" <philipoakley@iee.org> writes:
> 
>> From: "Lars Schneider" <larsxschneider@gmail.com>
>>> Many open source projects use github.com for their contribution process.
>>> Although we mirror the Git core repository to github.com [1] we do not
>>> use any other github.com service. This is unknown/unexpected to a
>>> number of (potential) contributors and consequently they create Pull
>>> Requests against our mirror with their contributions. These Pull
>>> Requests become stall [2]. This is frustrating to them as they think we
>>> ignore them and it is also unsatisfactory for us as we miss potential
>>> code improvements and/or new contributors.
>>> 
>>> GitHub offers a way to notify Pull Request contributors about the
>>> contribution guidelines for a project [3]. Let's make use of this!
>>> 
>>> [1] https://github.com/git/git
>>> [2] https://github.com/git/git/pulls
>>> [3]
>>> https://help.github.com/articles/creating-a-pull-request-template-for-your-repository/
>>> 
>>> Signed-off-by: Lars Schneider <larsxschneider@gmail.com>
>>> ---
>> 
>> I see there are currently 84 open PRs (13 in the last 14 days), so it
>> is real.
> 
> Not so insignificant fraction of these are done purely for the
> purpose of using submitgit, though.  In other words, if submitgit
> were improved not to require a pull request against [1] (instead, it
> could be pointed at a branch in a contributor's repository and do
> the fromatting), these numbers will go down.

As an alternative, could SubmitGit close the Pull Request automatically
after the mails have been send successfully?


>>> +Thanks for taking the time to contribute to Git! Please be advised,
>>> that the Git community does not use github.com for their
>>> contributions. Instead, we use a [mailing
>>> list](http://public-inbox.org/git/) for code submissions, code
>>> reviews, and bug reports.
>> 
>> Isn't the mailing list git@vger.kernel.org, with an archive at
>> http://public-inbox.org/git/ ?
>> 
> 
> I agree that I found the URL of the archive somewhat misleading for
> those who want to contribute.  Giving the mailing list address makes
> a lot more sense.  As suggested by Ævar in the thread, it would also
> be good to suggest submitgit, given that the target audience of this
> message was already prepared to throw a pull request at us.

OK, will fix!


>>> +Please [read the maintainer
>>> notes](http://repo.or.cz/w/git.git?a=blob_plain;f=MaintNotes;hb=todo)
>>> to learn how the Git
> 
> Two minor issues here.
> 
> 1. push the "read" outside [], i.e.
> 
> 	Please read [<human readable name of the thing>](<URL for
> 	the thing>) to learn...
> 
>   as what is inside [] and what is inside () ought to be the moral
>   equivalents.
> 
> 2. the thing is not called "the maintainer notes"; it is called "A
>   note from the maintainer". 

OK, will fix!


>> Is using the repo.or.cz address deliberate as a way of highlighting
>> that Github isn't the centre of the universe when accessing a DVCS
>> repo?
>> 
>> Maybe the kernel.org repo should be first, or at least the alt-git.git
>> repo at repo.or.cz listed in those same notes.
> 
> I'd prefer [the k.org address](https://git.kernel.org/pub/scm/git/git.git/plain/MaintNotes?h=todo).

OK, will fix!


> 
>>> +project is managed, and how you can work with it. In addition, we
>>> highly recommend you to [read our submission
>>> guidelines](../Documentation/SubmittingPatches).
> 
> Again, push "read our" outside [].

OK, will fix!

Thanks,
Lars

Re: [PATCH v1] Configure Git contribution guidelines for github.com

[Lars Schneider]

> On 10 Jun 2017, at 14:48, Philip Oakley <philipoakley@iee.org> wrote:
> 
> From: "Lars Schneider" <larsxschneider@gmail.com>
>> Many open source projects use github.com for their contribution process.
>> Although we mirror the Git core repository to github.com [1] we do not
>> use any other github.com service. This is unknown/unexpected to a
>> number of (potential) contributors and consequently they create Pull
>> Requests against our mirror with their contributions. These Pull
>> Requests become stall [2]. This is frustrating to them as they think we
>> ignore them and it is also unsatisfactory for us as we miss potential
>> code improvements and/or new contributors.
>> 
>> GitHub offers a way to notify Pull Request contributors about the
>> contribution guidelines for a project [3]. Let's make use of this!
>> 
>> [1] https://github.com/git/git
>> [2] https://github.com/git/git/pulls
>> [3] https://help.github.com/articles/creating-a-pull-request-template-for-your-repository/
>> 
>> Signed-off-by: Lars Schneider <larsxschneider@gmail.com>
>> ---
> 
> I see there are currently 84 open PRs (13 in the last 14 days), so it is real.
> 
> I also see that the Issues page for git.git appears to be disabled, and will redirect to the pulls page.
> 
> Maybe the instructions should also be part of an Issues template which could reduce the potential number of PRs being created (but could create its own problems)

I don't think that is necessary as Issues are disabled for this repo.

>> ...

>> +Thanks for taking the time to contribute to Git! Please be advised, that the Git community does not use github.com for their contributions. Instead, we use a [mailing list](http://public-inbox.org/git/) for code submissions, code reviews, and bug reports.
> 
> Isn't the mailing list git@vger.kernel.org, with an archive at http://public-inbox.org/git/ ?

Agreed!

> 
>> +
>> +Please [read the maintainer notes](http://repo.or.cz/w/git.git?a=blob_plain;f=MaintNotes;hb=todo) to learn how the Git
> 
> Is using the repo.or.cz address deliberate as a way of highlighting that Github isn't the centre of the universe when accessing a DVCS repo?

Haha, partly yes. Plus, I wasn't able to figure out quickly how to access the todo blob on GitHub. 


> Maybe the kernel.org repo should be first, or at least the alt-git.git repo at repo.or.cz listed in those same notes.

Agreed!


> It's still a good idea though.

Thanks :)


- Lars

Re: [PATCH v1] Configure Git contribution guidelines for github.com

[Lars Schneider]

> On 10 Jun 2017, at 09:35, Jeff King <peff@peff.net> wrote:
> 
> On Fri, Jun 09, 2017 at 10:03:57AM -0700, Jonathan Nieder wrote:
> 
>> Would putting a PULL_REQUEST_TEMPLATE and CONTRIBUTING in the
>> top-level directory work?  If I'm reading
>> https://help.github.com/articles/setting-guidelines-for-repository-contributors/#adding-a-contributing-file
>> correctly then it seems to say the ".github/" prefix is optional.
> 
> Yes, that should work. The ".github" option is there if you don't want
> the cruft at your top-level. I don't mind CONTRIBUTING, but
> PULL_REQUEST_TEMPLATE is kind of gross. :)

I think so, too :)


>> I also find the long source lines hard to read.  Can you say more
>> about how broken lines render in the github.com web interface?  I
>> would have expected github's markdown renderer to behave like others
>> and cope with line wrapping.
> 
> GitHub-Flavored Markdown treats newlines as a line break in the rendered
> output, unlike the original Markdown implementation. I don't like that
> myself, but it was done in the early days after seeing how many people
> accidentally butchered their formatting because they expected the output
> to look more like what they typed.

That's what I had in my memory based on past experience, too. However, 
out of curiosity I just tried it and it looks like they have changed it.
I'll reformat with 80 chars.

- Lars

Re: [PATCH v1] Configure Git contribution guidelines for github.com

[Lars Schneider]

> On 10 Jun 2017, at 03:51, Junio C Hamano <gitster@pobox.com> wrote:
> 
> Jonathan Nieder <jrnieder@gmail.com> writes:
> 
>> Lars Schneider wrote:
>> 
>>> Many open source projects use github.com for their contribution process.
>>> Although we mirror the Git core repository to github.com [1] we do not
>>> use any other github.com service. This is unknown/unexpected to a
>>> number of (potential) contributors and consequently they create Pull
>>> Requests against our mirror with their contributions. These Pull
>>> Requests become stall [2]. This is frustrating to them as they think we
>>> ignore them and it is also unsatisfactory for us as we miss potential
>>> code improvements and/or new contributors.
>> 
>> I think this description could be more focused.  It's also not
>> self-contained --- e.g. the link to stalled pull requests is likely to
>> become stale over time, especially if GitHub gives us a way to disable
>> pull requests for the repository some day.
>> 
>> Could you summarize for me the motivation behind this patch?  Is it to
>> make Git more approachable, to avoid frustrating contributors, etc?
> 
> I wonder if s/stall/stale/ is what Lars meant.

Of course :)

- Lars

Re: [PATCH v1] Configure Git contribution guidelines for github.com

[Ævar Arnfjörð Bjarmason]

On Mon, Jun 12, 2017 at 5:52 PM, Junio C Hamano <gitster@pobox.com> wrote:
> "Philip Oakley" <philipoakley@iee.org> writes:
>
>> From: "Lars Schneider" <larsxschneider@gmail.com>
>>> Many open source projects use github.com for their contribution process.
>>> Although we mirror the Git core repository to github.com [1] we do not
>>> use any other github.com service. This is unknown/unexpected to a
>>> number of (potential) contributors and consequently they create Pull
>>> Requests against our mirror with their contributions. These Pull
>>> Requests become stall [2]. This is frustrating to them as they think we
>>> ignore them and it is also unsatisfactory for us as we miss potential
>>> code improvements and/or new contributors.
>>>
>>> GitHub offers a way to notify Pull Request contributors about the
>>> contribution guidelines for a project [3]. Let's make use of this!
>>>
>>> [1] https://github.com/git/git
>>> [2] https://github.com/git/git/pulls
>>> [3]
>>> https://help.github.com/articles/creating-a-pull-request-template-for-your-repository/
>>>
>>> Signed-off-by: Lars Schneider <larsxschneider@gmail.com>
>>> ---

[The latest patch in this thread looks good to me to, thanks Lars]

>> I see there are currently 84 open PRs (13 in the last 14 days), so it
>> is real.
>
> Not so insignificant fraction of these are done purely for the
> purpose of using submitgit, though.  In other words, if submitgit
> were improved not to require a pull request against [1] (instead, it
> could be pointed at a branch in a contributor's repository and do
> the fromatting), these numbers will go down.

There are things we get out of this that would regress if
submitGit were changed this way:

 * Now when you submit a pull request you get a Travis build for
git/git, I don't get this if I push to any random branch in my
avar/git, and although I could probably set it up, it's extra work
etc.

 * I like being able to "git fetch" patches I'm reviewing. Now I can
just set "+refs/pull/*:refs/remotes/origin/pull/*" in the refspec for
git/git, if it were pulling from target repos I'd need to "git remote
add" for each one, not a big deal, but less convenient.

 * There would be no single place to list submitGit requests, which
you can do now through the pull page, although I think this is largely
stale now because nothing auto-closes them if they're merged (by which
point they'll have different sha1s), but that could be improved with
some bot...

There's probably ways to do this without git/git pull requests, but I
don't see what problem would be solved by moving this off git/git,
even if there's open requests submitGit is the only thing using these,
and any confusion about that pull UI would remain if it wasn't (AFAIK
there's no way to completely disable pull requests on github, but I
may be wrong).

Re: [PATCH v1] Configure Git contribution guidelines for github.com

[Junio C Hamano]

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

> There are things we get out of this that would regress if
> submitGit were changed this way:
>
>  * Now when you submit a pull request you get a Travis build for
> git/git, I don't get this if I push to any random branch in my
> avar/git, and although I could probably set it up, it's extra work
> etc.

Thanks for pointing this out.  I agree that this indeed is a
downside.

>  * I like being able to "git fetch" patches I'm reviewing. Now I can
> just set "+refs/pull/*:refs/remotes/origin/pull/*" in the refspec for
> git/git, if it were pulling from target repos I'd need to "git remote
> add" for each one, not a big deal, but less convenient.
>
>  * There would be no single place to list submitGit requests, which
> you can do now through the pull page, although I think this is largely
> stale now because nothing auto-closes them if they're merged (by which
> point they'll have different sha1s), but that could be improved with
> some bot...

I do not think these two are 'regressions', unless your definition
of 'regression' is a "this thing I used to be able to do, now I no
longer can", which is slightly different from mine, which is "this
useful thing I used to be able to do, now I no longer can".

It would be useful to be able to do the above two things, if the
list of submitGit requests and what you can get from pull/*
hierarchy (1) covered most of the changes proposed, allowing people
to check only this place and nowhere else, and/or (2) covered the
more interesting changes that are worth looking at than other
proposed changes.

I do not think either is the case.  The submitGit mechanism being an
easier way to propose a change to the mailing list, by definition,
(1) will not hold true.  And among the changes proposed to be made
to Git, the "selection criteria" to be in the set to be discoverable
by going to github.com/git/git.git and checking the submitGit pull
requests is not that they are of higher quality or touch interesting
topics.  The only common trait these proposed changes share, compared
to other proposed changes we see on the mailing list, are that they
were originally made as pull requests and (2) will not hold true.

Another thing that may regress that you did not mention is that we
would lose a convenient way to _count_ proposed changes coming via
submitGit (i.e. you can simply go to the pull-request page), so that
the number can be compared with the number of proposed changes
directly made on the mailing list, which would be a good way to
gauge how submitGit service is helping our community.  But even for
that, you'd need to go to the list to find the denominator
(i.e. total number of changes proposed), and by the time you do
that, counting the numerator (i.e. those come via submitGit) by
finding the telltale sign submitGit leaves in its output among these
denominator messages should be trivial.

So in all, I see the only downside is the loss of automated
triggering of Travis.  But I do agree with you that it is a rather
significant downside.

> There's probably ways to do this without git/git pull requests, but I
> don't see what problem would be solved by moving this off git/git,
> even if there's open requests submitGit is the only thing using these,
> and any confusion about that pull UI would remain if it wasn't (AFAIK
> there's no way to completely disable pull requests on github, but I
> may be wrong).

Hopefully the pull-request template update Lars proposes will keep
the pull request useful, in that they create one and then have
submitGit relay it to the official channel.

Re: [PATCH v1] Configure Git contribution guidelines for github.com

[Andreas Heiduk]

Am 15.06.2017 um 18:43 schrieb Junio C Hamano:
> Another thing that may regress that you did not mention is that we
> would lose a convenient way to _count_ proposed changes coming via
> submitGit (i.e. you can simply go to the pull-request page), so that
> the number can be compared with the number of proposed changes
> directly made on the mailing list, which would be a good way to
> gauge how submitGit service is helping our community.  But even for
> that, you'd need to go to the list to find the denominator
> (i.e. total number of changes proposed), and by the time you do
> that, counting the numerator (i.e. those come via submitGit) by
> finding the telltale sign submitGit leaves in its output among these
> denominator messages should be trivial.

This numbers can be aquired quite easily if submitGit adds a defined
trailer to the converted commit message like this:

	Signed-off-by: Foo Bar <foo@bar>
	Submit-git-id: url-or-id-of-pr

Re: [PATCH v1] Configure Git contribution guidelines for github.com

[Junio C Hamano]

Andreas Heiduk <asheiduk@gmail.com> writes:

> Am 15.06.2017 um 18:43 schrieb Junio C Hamano:
>> Another thing that may regress that you did not mention is that we
>> would lose a convenient way to _count_ proposed changes coming via
>> submitGit (i.e. you can simply go to the pull-request page), so that
>> the number can be compared with the number of proposed changes
>> directly made on the mailing list, which would be a good way to
>> gauge how submitGit service is helping our community.  But even for
>> that, you'd need to go to the list to find the denominator
>> (i.e. total number of changes proposed), and by the time you do
>> that, counting the numerator (i.e. those come via submitGit) by
>> finding the telltale sign submitGit leaves in its output among these
>> denominator messages should be trivial.
>
> This numbers can be aquired quite easily if submitGit adds a defined
> trailer to the converted commit message like this:
>
> 	Signed-off-by: Foo Bar <foo@bar>
> 	Submit-git-id: url-or-id-of-pr

I do not think you would want the noise _in_ the log message.  The
"telltale sign" I had in mind was these "signature" lines at the end
of the message:

    --
    https://github.com/git/git/pull/538