[openstack-dev] [all] Adding CONTRIBUTING.rst files to projects
akurilin at mirantis.com
Wed Dec 21 16:09:28 UTC 2016
On Wed, Dec 21, 2016 at 5:33 PM, Emilien Macchi <emilien at redhat.com> wrote:
> On Wed, Dec 21, 2016 at 10:22 AM, Ian Cordasco <sigmavirus24 at gmail.com>
> > Hey everyone,
> > It seems a contributor has written a script to add CONTRIBUTING.rst
> > files to each OpenStack project that exists. 
> 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
> > Is there value in having a CONTRIBUTING.rst to OpenStack?
> > =========================================================
> > Well, let's consider a few things:
> > * The canonical source for OpenStack repositories is
> > * 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
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
"forget everything you know".
If CONTRIBUTING.rst is widely used and it can help newcomers, I'm for
> > * 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
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"
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.
> > : https://review.openstack.org/#/q/owner:zhouyunfeng%40inspur.
> > --
> > Ian Cordasco
> > ____________________________________________________________
> > OpenStack Development Mailing List (not for usage questions)
> > Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> Emilien Macchi
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the OpenStack-dev