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

[PATCH v2] 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 stale. 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 contribution guidelines and a GitHub Pull Request template that
is visible to every Pull Request creator can be configured with special
files in a Git repository [2]. Let's make use of this!

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

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

Hi,

changes since v1:
* mention submitGit
* link to mailing list address instead of mailing list archive
* reformat long lines
* move "read" out of link title
* use kernel.org repo for "A note from the maintainer"
* reference "A note from the maintainer" with the correct name

You can see a preview here:
https://github.com/larsxschneider/git/compare/master...larsxschneider-patch-1?quick_pull=1

Thanks,
Lars


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

 .github/CONTRIBUTING.md          | 19 +++++++++++++++++++
 .github/PULL_REQUEST_TEMPLATE.md |  7 +++++++
 2 files changed, 26 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..fc397bb8fc
--- /dev/null
+++ b/.github/CONTRIBUTING.md
@@ -0,0 +1,19 @@
+## 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 (git@vger.kernel.org) for code submissions, code
+reviews, and bug reports.
+
+Nevertheless, you can use [submitGit](http://submitgit.herokuapp.com/) to
+conveniently send your Pull Requests commits to our mailing list.
+
+Please read ["A note from the maintainer"](https://git.kernel.org/pub/scm/git/git.git/plain/MaintNotes?h=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 friendly Git community!
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000000..2b617f4c25
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,7 @@
+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 (git@vger.kernel.org) for code submissions, code reviews, and
+bug reports. Nevertheless, you can use submitGit to conveniently send your Pull
+Requests commits to our mailing list.
+
+Please read the "guidelines for contributing" linked above!

base-commit: 8d1b10321b20bd2a73a5b561cfc3cf2e8051b70b
--
2.13.0

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

[Jeff King]

On Tue, Jun 13, 2017 at 10:18:07AM +0200, Lars Schneider wrote:

> changes since v1:
> * mention submitGit
> * link to mailing list address instead of mailing list archive

You might want to link to https://git-scm.com/community/, which has a
section on the mailing list at the top. It gives the list address but
also talks about the archive, that you can send to it without
subscribing, etc.

> * reformat long lines

I think this is OK. For CONTRIBUTING.md, GitHub re-wraps. In the pull
request template itself, though, the newlines become hard-wraps. But we
wouldn't generally expect those lines to remain in the final PR text
anyway, so it shouldn't really matter.

That's actually one annoyance I have with PR and issue templates like
this: the submitter has to manually delete them. But there's not really
a better way to get people's attention. The link to CONTRIBUTING is by
far not enough in my experience (I had to put a template in
git/git-scm.com for people to top submitting Git bugs).

The text itself looks good, but two minor grammar nits:

> diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
> new file mode 100644
> index 0000000000..fc397bb8fc
> --- /dev/null
> +++ b/.github/CONTRIBUTING.md
> @@ -0,0 +1,19 @@
> +## 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 (git@vger.kernel.org) for code submissions, code
> +reviews, and bug reports.

I think the comma after "advised" is unnecessary (you could also drop
"that" to turn the first part into an introductory clause, but I think
it reads better with as "Please be advised that").

> diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
> new file mode 100644
> index 0000000000..2b617f4c25
> --- /dev/null
> +++ b/.github/PULL_REQUEST_TEMPLATE.md
> @@ -0,0 +1,7 @@
> +Thanks for taking the time to contribute to Git! Please be advised, that the

Ditto here.

-Peff

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

[Lars Schneider]

> On 13 Jun 2017, at 11:04, Jeff King <peff@peff.net> wrote:
> 
> On Tue, Jun 13, 2017 at 10:18:07AM +0200, Lars Schneider wrote:
> 
>> changes since v1:
>> * mention submitGit
>> * link to mailing list address instead of mailing list archive
> 
> You might want to link to https://git-scm.com/community/, which has a
> section on the mailing list at the top. It gives the list address but
> also talks about the archive, that you can send to it without
> subscribing, etc.

Agreed. I removed the mailing list email address as this is not
useful until you have subscribed to the list.

> 
> The text itself looks good, but two minor grammar nits:
> 
>> diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
>> new file mode 100644
>> index 0000000000..fc397bb8fc
>> --- /dev/null
>> +++ b/.github/CONTRIBUTING.md
>> @@ -0,0 +1,19 @@
>> +## 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 (git@vger.kernel.org) for code submissions, code
>> +reviews, and bug reports.
> 
> I think the comma after "advised" is unnecessary (you could also drop
> "that" to turn the first part into an introductory clause, but I think
> it reads better with as "Please be advised that").

Agreed!

Thank you,
Lars

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

[Junio C Hamano]

Lars Schneider <larsxschneider@gmail.com> writes:

>> On 13 Jun 2017, at 11:04, Jeff King <peff@peff.net> wrote:
>> 
>> On Tue, Jun 13, 2017 at 10:18:07AM +0200, Lars Schneider wrote:
>> 
>>> changes since v1:
>>> * mention submitGit
>>> * link to mailing list address instead of mailing list archive
>> 
>> You might want to link to https://git-scm.com/community/, which has a
>> section on the mailing list at the top. It gives the list address but
>> also talks about the archive, that you can send to it without
>> subscribing, etc.
>
> Agreed. I removed the mailing list email address as this is not
> useful until you have subscribed to the list.

Wait a minite.  As Peff explained above, you *can* send to it
without subscribing, so "as this is not useful until you have
subscribed" is quite wrong, no?

>> The text itself looks good, but two minor grammar nits:
>> ... 
>
> Agreed!

This I think I've already squashed in to v2 before pushing the
result out.

I do not terribly mind what you did in v3 to the list address,
and I do agree with Peff that mentioning the "community" page
is a good idea.  But

     Git community does not use github.com for their contributions. Instead, we use
     a [mailing list](https://git-scm.com/community/) for code submissions,...
     ... and bug reports.

looks quite wrong.  If it were

     Git community does not use github.com for their contributions. Instead, we use
     a [mailing list](mailto:git@vger.kernel.org) for code submissions,...
     ... and bug reports.  See [the community page](https://git-scm.com/community/)
     for further information.

I won't find it questionable at all, though.

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

[Lars Schneider]

> On 14 Jun 2017, at 12:01, Junio C Hamano <gitster@pobox.com> wrote:
> 
> Lars Schneider <larsxschneider@gmail.com> writes:
> 
>>> On 13 Jun 2017, at 11:04, Jeff King <peff@peff.net> wrote:
>>> 
>>> On Tue, Jun 13, 2017 at 10:18:07AM +0200, Lars Schneider wrote:
>>> 
>>>> changes since v1:
>>>> * mention submitGit
>>>> * link to mailing list address instead of mailing list archive
>>> 
>>> You might want to link to https://git-scm.com/community/, which has a
>>> section on the mailing list at the top. It gives the list address but
>>> also talks about the archive, that you can send to it without
>>> subscribing, etc.
>> 
>> Agreed. I removed the mailing list email address as this is not
>> useful until you have subscribed to the list.
> 
> Wait a minite.  As Peff explained above, you *can* send to it
> without subscribing, so "as this is not useful until you have
> subscribed" is quite wrong, no?

Oh, I didn't know that! I "subscribed" before sending my first
message :)


> 
>>> The text itself looks good, but two minor grammar nits:
>>> ... 
>> 
>> Agreed!
> 
> This I think I've already squashed in to v2 before pushing the
> result out.
> 
> I do not terribly mind what you did in v3 to the list address,
> and I do agree with Peff that mentioning the "community" page
> is a good idea.  But
> 
>     Git community does not use github.com for their contributions. Instead, we use
>     a [mailing list](https://git-scm.com/community/) for code submissions,...
>     ... and bug reports.
> 
> looks quite wrong.  If it were
> 
>     Git community does not use github.com for their contributions. Instead, we use
>     a [mailing list](mailto:git@vger.kernel.org) for code submissions,...
>     ... and bug reports.  See [the community page](https://git-scm.com/community/)
>     for further information.

Looks good to me (minor nit: maybe s/the community page/our community page/ for a
more personal touch?). However, I would apply these changes only to CONTRIBUTING.md.
Markdown links wouldn't work in PULL_REQUEST_TEMPLATE.md as the user would see
the Markdown in plain text and not rendered.

Example here:
https://github.com/larsxschneider/git/compare/master...larsxschneider-patch-1?quick_pull=1

Thanks,
Lars