Open Stack

Hey everyone,

It seems a contributor has written a script to add CONTRIBUTING.rst
files to each OpenStack project that exists. [1]

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
* 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.
* 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). 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.

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