<div dir="ltr">Hi stackers!<br><div><div><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Dec 21, 2016 at 5:33 PM, Emilien Macchi <span dir="ltr"><<a href="mailto:emilien@redhat.com" target="_blank">emilien@redhat.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><span class="gmail-">On Wed, Dec 21, 2016 at 10:22 AM, Ian Cordasco <<a href="mailto:sigmavirus24@gmail.com">sigmavirus24@gmail.com</a>> wrote:<br>
> Hey everyone,<br>
><br>
> It seems a contributor has written a script to add CONTRIBUTING.rst<br>
> files to each OpenStack project that exists. [1]<br>
<br>
</span>Thanks Ian for starting this discussion, it's very appreciated.<br>
<br>
It would have been great if the author of these patches would have run<br>
this discussion before.<br>
Just for Puppet OpenStack projects, it has consumed ~450 CI jobs<br>
for... nothing (all patches will require some adjustments if we decide<br>
to keep this file).<br></blockquote><div><br></div><div>You can configure your heavy jobs to not be launched on *.rst changes ;)<br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
I can't imagine how many resources we consumed across all OpenStack<br>
projects with this batch of patches...<br>
<div><div class="gmail-h5"><br>
> As a community we've struggled with new contributors creating tonnes<br>
> of patches like this at once, and that is emphatically not the purpose<br>
> of this email. Instead, I'd like to discuss the actual merits of this<br>
> change for OpenStack.<br>
><br>
> What is CONTRIBUTING.rst?<br>
> =========================<br>
><br>
> It's a convention created by GitHub to make up for the lack of issue<br>
> templating and encourage collaborators/contributors to read some<br>
> documentation before filing new issues or pull requests. It does this<br>
> by adding an unobtrusive link at the top of the New Issue and New Pull<br>
> Request pages for projects that have these files.<br>
><br>
> In my experience using these files on projects, they've been wildly ineffective.<br>
><br>
> Is there value in having a CONTRIBUTING.rst to OpenStack?<br>
> ==============================<wbr>===========================<br>
><br>
> Well, let's consider a few things:<br>
><br>
> * The canonical source for OpenStack repositories is <a href="https://git.openstack.org/" rel="noreferrer" target="_blank">https://git.openstack.org/</a><br>
> * OpenStack /mirrors/ to GitHub so when we add Badges to our README,<br>
> they're displayed there for people who find the projects there<br></div></div></blockquote><div><br>Adding Badges is a sign that there are a lot of people who like finding everything in project <br>repository.<br></div><div>GitHub is just a mirror, but it is a first link of results list while googling, <a href="http://git.openstack.org">git.openstack.org</a> is:<br> - a second link in case of "openstack nova git" query; <br> - a third link in case of "openstack keystone git;"<br> - a fourth link in case of "openstack horizon git".<br><br>GitHub is a nice entry-point for new contributors. I do not want to say them <br>"forget everything you know".<br>If CONTRIBUTING.rst is widely used and it can help newcomers, I'm for adding it.<br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div><div class="gmail-h5">
> * OpenStack auto-closes all pull requests made to the GitHub mirrors<br>
> with instructions on how to contribute<br>
> * Having these files isn't really a *standard*. Other services<br>
> (GitLab, BitBucket) have added support for these files, but when you<br>
> look at projects not hosted on one of those service, these files<br>
> aren't as common.<br></div></div></blockquote><div><br></div><div>If GitHub, GitLab, BitBucket support that file, having CONTRIBUTING.rst sounds like <br>a standard for me.<br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div><div class="gmail-h5">
> * GitHub now allows the files that they look for to be in a .github<br>
> directory so the root of the repository isn't cluttered with markdown<br>
> and other files that only GitHub cares about for providing poorly made<br>
> bandaids for serious issues in their platform.<br>
><br>
> I'm not sure there's a great deal of benefit to OpenStack projects in<br>
> these patches. I'm sure most of us don't ever look to see how many<br>
> pull requests get opened against the GitHub mirrors. I doubt these<br>
> files would stop anyone from sending pull requests there in the first<br>
> place (based entirely on my own, purely anecdotal experiences).<br>
><br>
> Further, OpenStack already has a great deal of cross-project and<br>
> project-specific documentation around contributing that's easily<br>
> findable. Making that slightly more discoverable probably isn't a bad<br>
> thing.<br>
><br>
> On top of that, some projects have had CONTRIBUTING.rst files for a<br>
> while (Glance's goes back at least to 2014). </div></div></blockquote><div><br></div><div>Nova has it since  21 Nov 2012 ;)<br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div><div class="gmail-h5">Standardization about<br>
> where to look for that info wouldn't hurt us at all.<br>
><br>
> That said, I think there are two better places for this information<br>
> that are already standards in OpenStack:<br>
><br>
> * README.rst<br>
> * HACKING.rst<br>
><br>
> Most projects include links to the contributing documentation in at<br>
> least one of these files. I think the effort here is to standardize,<br>
> albeit in a brand new file, and that's admirable.<br>
<br></div></div></blockquote><div><br>It is true. Regularly, README.rst includes "how-to contribute" stuff, but <br>"ideal" README should describe a lot of things about projects and it can <br>become huge enough, so new contributors can miss "how-to contribute" section <br>there (README often doesn't have content list at the top of file).<br></div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div><div class="gmail-h5">
</div></div>+1 on those files.<br>
<span class="gmail-im gmail-HOEnZb"><br>
> If you look at the gerrit query, some projects have already merged or<br>
> abandoned some of the patches. Let's see if we can come to an<br>
> agreement about how to improve the experience for people finding our<br>
> projects and wanting to collaborate with us.<br>
><br>
> [1]: <a href="https://review.openstack.org/#/q/owner:zhouyunfeng%40inspur.com+topic:addCONTRIBUTING.rst" rel="noreferrer" target="_blank">https://review.openstack.org/#<wbr>/q/owner:zhouyunfeng%40inspur.<wbr>com+topic:addCONTRIBUTING.rst</a><br>
> --<br>
> Ian Cordasco<br>
><br>
> ______________________________<wbr>______________________________<wbr>______________<br>
> OpenStack Development Mailing List (not for usage questions)<br>
> Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.<wbr>openstack.org?subject:<wbr>unsubscribe</a><br>
> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/<wbr>cgi-bin/mailman/listinfo/<wbr>openstack-dev</a><br>
<br>
<br>
<br>
</span><span class="gmail-HOEnZb"><font color="#888888">--<br>
Emilien Macchi<br>
</font></span><div class="gmail-HOEnZb"><div class="gmail-h5"><br>
______________________________<wbr>______________________________<wbr>______________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.<wbr>openstack.org?subject:<wbr>unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/<wbr>cgi-bin/mailman/listinfo/<wbr>openstack-dev</a><br>
</div></div></blockquote></div><br><br clear="all"><br>-- <br><div class="gmail_signature"><div dir="ltr">Best regards,<br>Andrey Kurilin.<br></div></div>
</div></div></div></div>