Open Stack

-----Original Message-----
From: Andrey Kurilin <akurilin at mirantis.com>
Reply: OpenStack Development Mailing List (not for usage questions) <openstack-dev at lists.openstack.org>
Date: December 21, 2016 at 10:11:42
To: OpenStack Development Mailing List (not for usage questions) <openstack-dev at 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