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 <crobi...@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 -=-=-=-=-=-=-=-=-=-=-=- Groups.io Links: You receive all messages sent to this group. View/Reply Online (#64117): https://edk2.groups.io/g/devel/message/64117 Mute This Topic: https://groups.io/mt/76132077/21656 Group Owner: devel+ow...@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [arch...@mail-archive.com] -=-=-=-=-=-=-=-=-=-=-=-
