public inbox for devel@edk2.groups.io
 help / color / mirror / Atom feed
* [PATCH] Add a stub CONTRIBUTING.md pointing to the wiki
@ 2020-08-11 18:09 Cole
  2020-08-11 21:55 ` Laszlo Ersek
  0 siblings, 1 reply; 7+ messages in thread
From: Cole @ 2020-08-11 18:09 UTC (permalink / raw)
  To: devel; +Cc: michael.d.kinney, lersek, Cole Robinson

Googling for 'edk2 pull request' did not find this wiki page:

https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Development-Process

Add it to CONTRIBUTING.md for more discoverability

Signed-off-by: Cole Robinson <crobinso@redhat.com>
---
I tried submitting a PR to edk2: https://github.com/tianocore/edk2/pull/854

It was auto closed with: `All checks passed. Auto close personal build.`

That confused me quite a bit. I could not understand what it was trying
to say. I looked at other successfully merged PRs, noticed some hits
about a 'push' label, but on looking to resubmit the PR it didn't seem
like I had permission to set labels. Googling did not turn up any explanatory
hits in the first two pages either. Eventually Laszlo pointed me in the
right direction though

A couple other suggestions to avoid that confusion

* Extend the mergify message to clarify PRs are largely only meant for
  maintainers to use. Maybe point at the wiki page or CONTRIBUTING.md

* Add a github new PR template with a comment giving more explanation:
https://docs.github.com/en/github/building-a-strong-community/creating-a-pull-request-template-for-your-repository

 CONTRIBUTING.md | 3 +++
 1 file changed, 3 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000000..212c69ce8b
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,3 @@
+# Contributing to EDK2
+
+Contributor documentation is maintained on the wiki: https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Development-Process
-- 
2.26.2


^ permalink raw reply related	[flat|nested] 7+ messages in thread

* Re: [PATCH] Add a stub CONTRIBUTING.md pointing to the wiki
  2020-08-11 18:09 [PATCH] Add a stub CONTRIBUTING.md pointing to the wiki Cole
@ 2020-08-11 21:55 ` Laszlo Ersek
  2020-08-11 22:51   ` Cole
  0 siblings, 1 reply; 7+ messages in thread
From: Laszlo Ersek @ 2020-08-11 21:55 UTC (permalink / raw)
  To: Cole Robinson, devel; +Cc: michael.d.kinney

On 08/11/20 20:09, Cole Robinson wrote:
> Googling for 'edk2 pull request' did not find this wiki page:
> 
> https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Development-Process
> 
> Add it to CONTRIBUTING.md for more discoverability
> 
> Signed-off-by: Cole Robinson <crobinso@redhat.com>
> ---
> I tried submitting a PR to edk2: https://github.com/tianocore/edk2/pull/854
> 
> It was auto closed with: `All checks passed. Auto close personal build.`
> 
> That confused me quite a bit. I could not understand what it was trying
> to say. I looked at other successfully merged PRs, noticed some hits
> about a 'push' label, but on looking to resubmit the PR it didn't seem
> like I had permission to set labels. Googling did not turn up any explanatory
> hits in the first two pages either. Eventually Laszlo pointed me in the
> right direction though
> 
> A couple other suggestions to avoid that confusion
> 
> * Extend the mergify message to clarify PRs are largely only meant for
>   maintainers to use. Maybe point at the wiki page or CONTRIBUTING.md
> 
> * Add a github new PR template with a comment giving more explanation:
> https://docs.github.com/en/github/building-a-strong-community/creating-a-pull-request-template-for-your-repository
> 
>  CONTRIBUTING.md | 3 +++
>  1 file changed, 3 insertions(+)
>  create mode 100644 CONTRIBUTING.md
> 
> diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
> new file mode 100644
> index 0000000000..212c69ce8b
> --- /dev/null
> +++ b/CONTRIBUTING.md
> @@ -0,0 +1,3 @@
> +# Contributing to EDK2
> +
> +Contributor documentation is maintained on the wiki: https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Development-Process
> 

Does github display "CONTRIBUTING.md" automatically?

Hm... If I check <https://github.com/virt-manager/virt-manager/>, there's an explicit reference to "CONTRIBUTING.md" at the bottom of "README.md"; github.com seems to display "README.md" only.

Is this patch useful without modifying "ReadMe.rst"?


... Actually, the section at

  https://github.com/tianocore/edk2/#resources

includes "How To Contribute" ->

  https://github.com/tianocore/tianocore.github.io/wiki/How-To-Contribute

Is that unhelpful (or difficult to find)?

Thanks!
Laszlo


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] Add a stub CONTRIBUTING.md pointing to the wiki
  2020-08-11 21:55 ` Laszlo Ersek
@ 2020-08-11 22:51   ` Cole
  2020-08-12  9:37     ` Laszlo Ersek
  0 siblings, 1 reply; 7+ messages in thread
From: Cole @ 2020-08-11 22:51 UTC (permalink / raw)
  To: Laszlo Ersek, devel; +Cc: michael.d.kinney

On 8/11/20 5:55 PM, Laszlo Ersek wrote:
> On 08/11/20 20:09, Cole Robinson wrote:
>> Googling for 'edk2 pull request' did not find this wiki page:
>>
>> https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Development-Process
>>
>> Add it to CONTRIBUTING.md for more discoverability
>>
>> Signed-off-by: Cole Robinson <crobinso@redhat.com>
>> ---
>> I tried submitting a PR to edk2: https://github.com/tianocore/edk2/pull/854
>>
>> It was auto closed with: `All checks passed. Auto close personal build.`
>>
>> That confused me quite a bit. I could not understand what it was trying
>> to say. I looked at other successfully merged PRs, noticed some hits
>> about a 'push' label, but on looking to resubmit the PR it didn't seem
>> like I had permission to set labels. Googling did not turn up any explanatory
>> hits in the first two pages either. Eventually Laszlo pointed me in the
>> right direction though
>>
>> A couple other suggestions to avoid that confusion
>>
>> * Extend the mergify message to clarify PRs are largely only meant for
>>   maintainers to use. Maybe point at the wiki page or CONTRIBUTING.md
>>
>> * Add a github new PR template with a comment giving more explanation:
>> https://docs.github.com/en/github/building-a-strong-community/creating-a-pull-request-template-for-your-repository
>>
>>  CONTRIBUTING.md | 3 +++
>>  1 file changed, 3 insertions(+)
>>  create mode 100644 CONTRIBUTING.md
>>
>> diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
>> new file mode 100644
>> index 0000000000..212c69ce8b
>> --- /dev/null
>> +++ b/CONTRIBUTING.md
>> @@ -0,0 +1,3 @@
>> +# Contributing to EDK2
>> +
>> +Contributor documentation is maintained on the wiki: https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Development-Process
>>
> 
> Does github display "CONTRIBUTING.md" automatically?
> 
> Hm... If I check <https://github.com/virt-manager/virt-manager/>, there's an explicit reference to "CONTRIBUTING.md" at the bottom of "README.md"; github.com seems to display "README.md" only.
> 
> Is this patch useful without modifying "ReadMe.rst"?
> 

When submitting a new pull request via the web UI, github will link to
CONTRIBUTING.md for that repo if it exists. I just tried with
virt-manager: for first time PRs it will give a pop up notification, but
it also always shows a link in a small line underneath the initial PR
comment box. Previously it was linked at the top IIRC.

Some more info here:
https://docs.github.com/en/github/building-a-strong-community/setting-guidelines-for-repository-contributors

> 
> ... Actually, the section at
> 
>   https://github.com/tianocore/edk2/#resources
> 
> includes "How To Contribute" ->
> 
>   https://github.com/tianocore/tianocore.github.io/wiki/How-To-Contribute
> 
> Is that unhelpful (or difficult to find)?

I did not read the Readme TBH. I did grep sources for a link to that
wiki page you linked me, and 'pull request' to see if I was missing doc
links.

Maybe CONTRIBUTING.md isn't the way to go. I mostly wanted to start a
discussion about how to make it clear to drive-by contributors that PRs
aren't meant for them. Changing the mergify message or pull request
message template is more targeted. But they will probably want to link
to a document that explains the PR workflow better, and that
EDK-II-Development-Process is the closest I've seen so far

Thanks,
Cole


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] Add a stub CONTRIBUTING.md pointing to the wiki
  2020-08-11 22:51   ` Cole
@ 2020-08-12  9:37     ` Laszlo Ersek
  2020-08-12 16:00       ` Cole
  2020-08-18 18:17       ` [edk2-devel] " Laszlo Ersek
  0 siblings, 2 replies; 7+ messages in thread
From: Laszlo Ersek @ 2020-08-12  9:37 UTC (permalink / raw)
  To: Cole Robinson, devel
  Cc: michael.d.kinney, Leif Lindholm (Nuvia address), Andrew Fish

[-- Attachment #1: Type: text/plain, Size: 4460 bytes --]

On 08/12/20 00:51, Cole Robinson wrote:
> On 8/11/20 5:55 PM, Laszlo Ersek wrote:
>> On 08/11/20 20:09, Cole Robinson wrote:
>>> Googling for 'edk2 pull request' did not find this wiki page:
>>>
>>> https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Development-Process
>>>
>>> Add it to CONTRIBUTING.md for more discoverability
>>>
>>> Signed-off-by: Cole Robinson <crobinso@redhat.com>
>>> ---
>>> I tried submitting a PR to edk2: https://github.com/tianocore/edk2/pull/854
>>>
>>> It was auto closed with: `All checks passed. Auto close personal build.`
>>>
>>> That confused me quite a bit. I could not understand what it was trying
>>> to say. I looked at other successfully merged PRs, noticed some hits
>>> about a 'push' label, but on looking to resubmit the PR it didn't seem
>>> like I had permission to set labels. Googling did not turn up any explanatory
>>> hits in the first two pages either. Eventually Laszlo pointed me in the
>>> right direction though
>>>
>>> A couple other suggestions to avoid that confusion
>>>
>>> * Extend the mergify message to clarify PRs are largely only meant for
>>>   maintainers to use. Maybe point at the wiki page or CONTRIBUTING.md
>>>
>>> * Add a github new PR template with a comment giving more explanation:
>>> https://docs.github.com/en/github/building-a-strong-community/creating-a-pull-request-template-for-your-repository
>>>
>>>  CONTRIBUTING.md | 3 +++
>>>  1 file changed, 3 insertions(+)
>>>  create mode 100644 CONTRIBUTING.md
>>>
>>> diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
>>> new file mode 100644
>>> index 0000000000..212c69ce8b
>>> --- /dev/null
>>> +++ b/CONTRIBUTING.md
>>> @@ -0,0 +1,3 @@
>>> +# Contributing to EDK2
>>> +
>>> +Contributor documentation is maintained on the wiki: https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Development-Process
>>>
>>
>> Does github display "CONTRIBUTING.md" automatically?
>>
>> Hm... If I check <https://github.com/virt-manager/virt-manager/>, there's an explicit reference to "CONTRIBUTING.md" at the bottom of "README.md"; github.com seems to display "README.md" only.
>>
>> Is this patch useful without modifying "ReadMe.rst"?
>>
> 
> When submitting a new pull request via the web UI, github will link to
> CONTRIBUTING.md for that repo if it exists. I just tried with
> virt-manager: for first time PRs it will give a pop up notification, but
> it also always shows a link in a small line underneath the initial PR
> comment box. Previously it was linked at the top IIRC.
> 
> Some more info here:
> https://docs.github.com/en/github/building-a-strong-community/setting-guidelines-for-repository-contributors

This has convinced me, thanks. I've tried the above myself, and it is
indeed as you explain (see the screenshot with highlights attached). And
both highlighted links refer to:

https://github.com/virt-manager/virt-manager/blob/master/CONTRIBUTING.md


I suggest extending the commit message:

"""
Add it to CONTRIBUTING.md for more discoverability.

(When someone opens a pull request, they will see a link to
CONTRIBUTING.md; see
<https://docs.github.com/en/github/building-a-strong-community/setting-guidelines-for-repository-contributors>.)
"""

But we can edit the commit message like this this without a resubmit.


> 
>>
>> ... Actually, the section at
>>
>>   https://github.com/tianocore/edk2/#resources
>>
>> includes "How To Contribute" ->
>>
>>   https://github.com/tianocore/tianocore.github.io/wiki/How-To-Contribute
>>
>> Is that unhelpful (or difficult to find)?
> 
> I did not read the Readme TBH. I did grep sources for a link to that
> wiki page you linked me, and 'pull request' to see if I was missing doc
> links.
> 
> Maybe CONTRIBUTING.md isn't the way to go. I mostly wanted to start a
> discussion about how to make it clear to drive-by contributors that PRs
> aren't meant for them. Changing the mergify message or pull request
> message template is more targeted. But they will probably want to link
> to a document that explains the PR workflow better, and that
> EDK-II-Development-Process is the closest I've seen so far

I agree with both of your other suggestions (extending the mergify
message upon auto-close, and adding a PR template with some
explanation), but I'd also like us to apply this patch -- because github
does reference CONTRIBUTING.md automatically.

Reviewed-by: Laszlo Ersek <lersek@redhat.com>

Andrew, Leif, Mike, do you have comments?

Thanks!
Laszlo

[-- Attachment #2: gh-contributing.png --]
[-- Type: image/png, Size: 70066 bytes --]

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] Add a stub CONTRIBUTING.md pointing to the wiki
  2020-08-12  9:37     ` Laszlo Ersek
@ 2020-08-12 16:00       ` Cole
  2020-08-12 17:33         ` Laszlo Ersek
  2020-08-18 18:17       ` [edk2-devel] " Laszlo Ersek
  1 sibling, 1 reply; 7+ messages in thread
From: Cole @ 2020-08-12 16:00 UTC (permalink / raw)
  To: Laszlo Ersek, devel
  Cc: michael.d.kinney, Leif Lindholm (Nuvia address), Andrew Fish

On 8/12/20 5:37 AM, Laszlo Ersek wrote:
> On 08/12/20 00:51, Cole Robinson wrote:
>> On 8/11/20 5:55 PM, Laszlo Ersek wrote:
>>> On 08/11/20 20:09, Cole Robinson wrote:
>>>> Googling for 'edk2 pull request' did not find this wiki page:
>>>>
>>>> https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Development-Process
>>>>
>>>> Add it to CONTRIBUTING.md for more discoverability
>>>>
>>>> Signed-off-by: Cole Robinson <crobinso@redhat.com>
>>>> ---
>>>> I tried submitting a PR to edk2: https://github.com/tianocore/edk2/pull/854
>>>>
>>>> It was auto closed with: `All checks passed. Auto close personal build.`
>>>>
>>>> That confused me quite a bit. I could not understand what it was trying
>>>> to say. I looked at other successfully merged PRs, noticed some hits
>>>> about a 'push' label, but on looking to resubmit the PR it didn't seem
>>>> like I had permission to set labels. Googling did not turn up any explanatory
>>>> hits in the first two pages either. Eventually Laszlo pointed me in the
>>>> right direction though
>>>>
>>>> A couple other suggestions to avoid that confusion
>>>>
>>>> * Extend the mergify message to clarify PRs are largely only meant for
>>>>   maintainers to use. Maybe point at the wiki page or CONTRIBUTING.md
>>>>
>>>> * Add a github new PR template with a comment giving more explanation:
>>>> https://docs.github.com/en/github/building-a-strong-community/creating-a-pull-request-template-for-your-repository
>>>>
>>>>  CONTRIBUTING.md | 3 +++
>>>>  1 file changed, 3 insertions(+)
>>>>  create mode 100644 CONTRIBUTING.md
>>>>
>>>> diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
>>>> new file mode 100644
>>>> index 0000000000..212c69ce8b
>>>> --- /dev/null
>>>> +++ b/CONTRIBUTING.md
>>>> @@ -0,0 +1,3 @@
>>>> +# Contributing to EDK2
>>>> +
>>>> +Contributor documentation is maintained on the wiki: https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Development-Process
>>>>
>>>
>>> Does github display "CONTRIBUTING.md" automatically?
>>>
>>> Hm... If I check <https://github.com/virt-manager/virt-manager/>, there's an explicit reference to "CONTRIBUTING.md" at the bottom of "README.md"; github.com seems to display "README.md" only.
>>>
>>> Is this patch useful without modifying "ReadMe.rst"?
>>>
>>
>> When submitting a new pull request via the web UI, github will link to
>> CONTRIBUTING.md for that repo if it exists. I just tried with
>> virt-manager: for first time PRs it will give a pop up notification, but
>> it also always shows a link in a small line underneath the initial PR
>> comment box. Previously it was linked at the top IIRC.
>>
>> Some more info here:
>> https://docs.github.com/en/github/building-a-strong-community/setting-guidelines-for-repository-contributors
> 
> This has convinced me, thanks. I've tried the above myself, and it is
> indeed as you explain (see the screenshot with highlights attached). And
> both highlighted links refer to:
> 
> https://github.com/virt-manager/virt-manager/blob/master/CONTRIBUTING.md
> 
> 
> I suggest extending the commit message:
> 
> """
> Add it to CONTRIBUTING.md for more discoverability.
> 
> (When someone opens a pull request, they will see a link to
> CONTRIBUTING.md; see
> <https://docs.github.com/en/github/building-a-strong-community/setting-guidelines-for-repository-contributors>.)
> """
> 
> But we can edit the commit message like this this without a resubmit.
> 

ACK from me


> 
>>
>>>
>>> ... Actually, the section at
>>>
>>>   https://github.com/tianocore/edk2/#resources
>>>
>>> includes "How To Contribute" ->
>>>
>>>   https://github.com/tianocore/tianocore.github.io/wiki/How-To-Contribute
>>>
>>> Is that unhelpful (or difficult to find)?
>>
>> I did not read the Readme TBH. I did grep sources for a link to that
>> wiki page you linked me, and 'pull request' to see if I was missing doc
>> links.
>>
>> Maybe CONTRIBUTING.md isn't the way to go. I mostly wanted to start a
>> discussion about how to make it clear to drive-by contributors that PRs
>> aren't meant for them. Changing the mergify message or pull request
>> message template is more targeted. But they will probably want to link
>> to a document that explains the PR workflow better, and that
>> EDK-II-Development-Process is the closest I've seen so far
> 
> I agree with both of your other suggestions (extending the mergify
> message upon auto-close, and adding a PR template with some
> explanation), but I'd also like us to apply this patch -- because github
> does reference CONTRIBUTING.md automatically.
> 

The one bit to consider is whether the link I specified makes sense, or
if CONTRIBUTING.md should point to the link you suggested
https://github.com/tianocore/tianocore.github.io/wiki/How-To-Contribute
 which seems like it is the intended entry point for contributor info.

Thought that page should probably be updated to also point to
https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Development-Process

Thanks,
Cole


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] Add a stub CONTRIBUTING.md pointing to the wiki
  2020-08-12 16:00       ` Cole
@ 2020-08-12 17:33         ` Laszlo Ersek
  0 siblings, 0 replies; 7+ messages in thread
From: Laszlo Ersek @ 2020-08-12 17:33 UTC (permalink / raw)
  To: Cole Robinson, devel
  Cc: michael.d.kinney, Leif Lindholm (Nuvia address), Andrew Fish

On 08/12/20 18:00, Cole Robinson wrote:
> On 8/12/20 5:37 AM, Laszlo Ersek wrote:
>> On 08/12/20 00:51, Cole Robinson wrote:
>>> On 8/11/20 5:55 PM, Laszlo Ersek wrote:
>>>> On 08/11/20 20:09, Cole Robinson wrote:
>>>>> Googling for 'edk2 pull request' did not find this wiki page:
>>>>>
>>>>> https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Development-Process
>>>>>
>>>>> Add it to CONTRIBUTING.md for more discoverability
>>>>>
>>>>> Signed-off-by: Cole Robinson <crobinso@redhat.com>
>>>>> ---
>>>>> I tried submitting a PR to edk2: https://github.com/tianocore/edk2/pull/854
>>>>>
>>>>> It was auto closed with: `All checks passed. Auto close personal build.`
>>>>>
>>>>> That confused me quite a bit. I could not understand what it was trying
>>>>> to say. I looked at other successfully merged PRs, noticed some hits
>>>>> about a 'push' label, but on looking to resubmit the PR it didn't seem
>>>>> like I had permission to set labels. Googling did not turn up any explanatory
>>>>> hits in the first two pages either. Eventually Laszlo pointed me in the
>>>>> right direction though
>>>>>
>>>>> A couple other suggestions to avoid that confusion
>>>>>
>>>>> * Extend the mergify message to clarify PRs are largely only meant for
>>>>>   maintainers to use. Maybe point at the wiki page or CONTRIBUTING.md
>>>>>
>>>>> * Add a github new PR template with a comment giving more explanation:
>>>>> https://docs.github.com/en/github/building-a-strong-community/creating-a-pull-request-template-for-your-repository
>>>>>
>>>>>  CONTRIBUTING.md | 3 +++
>>>>>  1 file changed, 3 insertions(+)
>>>>>  create mode 100644 CONTRIBUTING.md
>>>>>
>>>>> diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
>>>>> new file mode 100644
>>>>> index 0000000000..212c69ce8b
>>>>> --- /dev/null
>>>>> +++ b/CONTRIBUTING.md
>>>>> @@ -0,0 +1,3 @@
>>>>> +# Contributing to EDK2
>>>>> +
>>>>> +Contributor documentation is maintained on the wiki: https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Development-Process
>>>>>
>>>>
>>>> Does github display "CONTRIBUTING.md" automatically?
>>>>
>>>> Hm... If I check <https://github.com/virt-manager/virt-manager/>, there's an explicit reference to "CONTRIBUTING.md" at the bottom of "README.md"; github.com seems to display "README.md" only.
>>>>
>>>> Is this patch useful without modifying "ReadMe.rst"?
>>>>
>>>
>>> When submitting a new pull request via the web UI, github will link to
>>> CONTRIBUTING.md for that repo if it exists. I just tried with
>>> virt-manager: for first time PRs it will give a pop up notification, but
>>> it also always shows a link in a small line underneath the initial PR
>>> comment box. Previously it was linked at the top IIRC.
>>>
>>> Some more info here:
>>> https://docs.github.com/en/github/building-a-strong-community/setting-guidelines-for-repository-contributors
>>
>> This has convinced me, thanks. I've tried the above myself, and it is
>> indeed as you explain (see the screenshot with highlights attached). And
>> both highlighted links refer to:
>>
>> https://github.com/virt-manager/virt-manager/blob/master/CONTRIBUTING.md
>>
>>
>> I suggest extending the commit message:
>>
>> """
>> Add it to CONTRIBUTING.md for more discoverability.
>>
>> (When someone opens a pull request, they will see a link to
>> CONTRIBUTING.md; see
>> <https://docs.github.com/en/github/building-a-strong-community/setting-guidelines-for-repository-contributors>.)
>> """
>>
>> But we can edit the commit message like this this without a resubmit.
>>
> 
> ACK from me
> 
> 
>>
>>>
>>>>
>>>> ... Actually, the section at
>>>>
>>>>   https://github.com/tianocore/edk2/#resources
>>>>
>>>> includes "How To Contribute" ->
>>>>
>>>>   https://github.com/tianocore/tianocore.github.io/wiki/How-To-Contribute
>>>>
>>>> Is that unhelpful (or difficult to find)?
>>>
>>> I did not read the Readme TBH. I did grep sources for a link to that
>>> wiki page you linked me, and 'pull request' to see if I was missing doc
>>> links.
>>>
>>> Maybe CONTRIBUTING.md isn't the way to go. I mostly wanted to start a
>>> discussion about how to make it clear to drive-by contributors that PRs
>>> aren't meant for them. Changing the mergify message or pull request
>>> message template is more targeted. But they will probably want to link
>>> to a document that explains the PR workflow better, and that
>>> EDK-II-Development-Process is the closest I've seen so far
>>
>> I agree with both of your other suggestions (extending the mergify
>> message upon auto-close, and adding a PR template with some
>> explanation), but I'd also like us to apply this patch -- because github
>> does reference CONTRIBUTING.md automatically.
>>
> 
> The one bit to consider is whether the link I specified makes sense, or
> if CONTRIBUTING.md should point to the link you suggested
> https://github.com/tianocore/tianocore.github.io/wiki/How-To-Contribute
>  which seems like it is the intended entry point for contributor info.
> 
> Thought that page should probably be updated to also point to
> https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Development-Process

One issue with documentation is that the more you add of it, the more it
constantly needs to be reorganized / refactored. All wikis always exist
at a level of both redundancy and blank spots.

I think the link in your patch is good.

Thanks
Laszlo


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [edk2-devel] [PATCH] Add a stub CONTRIBUTING.md pointing to the wiki
  2020-08-12  9:37     ` Laszlo Ersek
  2020-08-12 16:00       ` Cole
@ 2020-08-18 18:17       ` Laszlo Ersek
  1 sibling, 0 replies; 7+ messages in thread
From: Laszlo Ersek @ 2020-08-18 18:17 UTC (permalink / raw)
  To: Cole Robinson, devel
  Cc: michael.d.kinney, Leif Lindholm (Nuvia address), Andrew Fish

On 08/12/20 11:37, Laszlo Ersek wrote:
> On 08/12/20 00:51, Cole Robinson wrote:
>> On 8/11/20 5:55 PM, Laszlo Ersek wrote:
>>> On 08/11/20 20:09, Cole Robinson wrote:
>>>> Googling for 'edk2 pull request' did not find this wiki page:
>>>>
>>>> https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Development-Process
>>>>
>>>> Add it to CONTRIBUTING.md for more discoverability
>>>>
>>>> Signed-off-by: Cole Robinson <crobinso@redhat.com>
>>>> ---
>>>> I tried submitting a PR to edk2: https://github.com/tianocore/edk2/pull/854
>>>>
>>>> It was auto closed with: `All checks passed. Auto close personal build.`
>>>>
>>>> That confused me quite a bit. I could not understand what it was trying
>>>> to say. I looked at other successfully merged PRs, noticed some hits
>>>> about a 'push' label, but on looking to resubmit the PR it didn't seem
>>>> like I had permission to set labels. Googling did not turn up any explanatory
>>>> hits in the first two pages either. Eventually Laszlo pointed me in the
>>>> right direction though
>>>>
>>>> A couple other suggestions to avoid that confusion
>>>>
>>>> * Extend the mergify message to clarify PRs are largely only meant for
>>>>   maintainers to use. Maybe point at the wiki page or CONTRIBUTING.md
>>>>
>>>> * Add a github new PR template with a comment giving more explanation:
>>>> https://docs.github.com/en/github/building-a-strong-community/creating-a-pull-request-template-for-your-repository
>>>>
>>>>  CONTRIBUTING.md | 3 +++
>>>>  1 file changed, 3 insertions(+)
>>>>  create mode 100644 CONTRIBUTING.md
>>>>
>>>> diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
>>>> new file mode 100644
>>>> index 0000000000..212c69ce8b
>>>> --- /dev/null
>>>> +++ b/CONTRIBUTING.md
>>>> @@ -0,0 +1,3 @@
>>>> +# Contributing to EDK2
>>>> +
>>>> +Contributor documentation is maintained on the wiki: https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Development-Process
>>>>
>>>
>>> Does github display "CONTRIBUTING.md" automatically?
>>>
>>> Hm... If I check <https://github.com/virt-manager/virt-manager/>, there's an explicit reference to "CONTRIBUTING.md" at the bottom of "README.md"; github.com seems to display "README.md" only.
>>>
>>> Is this patch useful without modifying "ReadMe.rst"?
>>>
>>
>> When submitting a new pull request via the web UI, github will link to
>> CONTRIBUTING.md for that repo if it exists. I just tried with
>> virt-manager: for first time PRs it will give a pop up notification, but
>> it also always shows a link in a small line underneath the initial PR
>> comment box. Previously it was linked at the top IIRC.
>>
>> Some more info here:
>> https://docs.github.com/en/github/building-a-strong-community/setting-guidelines-for-repository-contributors
> 
> This has convinced me, thanks. I've tried the above myself, and it is
> indeed as you explain (see the screenshot with highlights attached). And
> both highlighted links refer to:
> 
> https://github.com/virt-manager/virt-manager/blob/master/CONTRIBUTING.md
> 
> 
> I suggest extending the commit message:
> 
> """
> Add it to CONTRIBUTING.md for more discoverability.
> 
> (When someone opens a pull request, they will see a link to
> CONTRIBUTING.md; see
> <https://docs.github.com/en/github/building-a-strong-community/setting-guidelines-for-repository-contributors>.)
> """
> 
> But we can edit the commit message like this this without a resubmit.
> 
> 
>>
>>>
>>> ... Actually, the section at
>>>
>>>   https://github.com/tianocore/edk2/#resources
>>>
>>> includes "How To Contribute" ->
>>>
>>>   https://github.com/tianocore/tianocore.github.io/wiki/How-To-Contribute
>>>
>>> Is that unhelpful (or difficult to find)?
>>
>> I did not read the Readme TBH. I did grep sources for a link to that
>> wiki page you linked me, and 'pull request' to see if I was missing doc
>> links.
>>
>> Maybe CONTRIBUTING.md isn't the way to go. I mostly wanted to start a
>> discussion about how to make it clear to drive-by contributors that PRs
>> aren't meant for them. Changing the mergify message or pull request
>> message template is more targeted. But they will probably want to link
>> to a document that explains the PR workflow better, and that
>> EDK-II-Development-Process is the closest I've seen so far
> 
> I agree with both of your other suggestions (extending the mergify
> message upon auto-close, and adding a PR template with some
> explanation), but I'd also like us to apply this patch -- because github
> does reference CONTRIBUTING.md automatically.
> 
> Reviewed-by: Laszlo Ersek <lersek@redhat.com>
> 
> Andrew, Leif, Mike, do you have comments?

Merged as commit 7e6f150b6902, via
<https://github.com/tianocore/edk2/pull/890>.

Thanks
Laszlo


^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, other threads:[~2020-08-18 18:17 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-08-11 18:09 [PATCH] Add a stub CONTRIBUTING.md pointing to the wiki Cole
2020-08-11 21:55 ` Laszlo Ersek
2020-08-11 22:51   ` Cole
2020-08-12  9:37     ` Laszlo Ersek
2020-08-12 16:00       ` Cole
2020-08-12 17:33         ` Laszlo Ersek
2020-08-18 18:17       ` [edk2-devel] " Laszlo Ersek

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox