Re: [PATCH] Add a stub CONTRIBUTING.md pointing to the wiki

["Cole" <crobinso@redhat.com>]

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