-----Original Message----- From: Andrey Kurilin <akuri...@mirantis.com> Reply: OpenStack Development Mailing List (not for usage questions) <openstack-dev@lists.openstack.org> Date: December 21, 2016 at 10:11:42 To: OpenStack Development Mailing List (not for usage questions) <openstack-dev@lists.openstack.org> Subject: Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects
> Hi stackers! > > On Wed, Dec 21, 2016 at 5:33 PM, Emilien Macchi wrote: > > > On Wed, Dec 21, 2016 at 10:22 AM, Ian Cordasco > > 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". Except that learning to contribute to projects on GitHub is far from useful for them when looking at a project like ours or an Apache Software Foundation project or some of the projects open sourced by companies like Google. > If CONTRIBUTING.rst is widely used and it can help newcomers, I'm for > adding it. Anecdotally speaking, it doesn't help new contributors though. Hence why I sent this email. If I felt it would have a measurable positive impact, I wouldn't have written this email. :) > > > * 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. That's not what defines a standard. One company coming up with a bandaid that a few others scrambled to support isn't a standard, it's a fad. > > > * 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. Right, I'm starting to think that it'd be better to use the README to point people at the HACKING files which include the relevant information, links, etc. -- 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
