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

["Laszlo Ersek" <lersek@redhat.com>]

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