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