Open Stack

On Wed, Dec 21, 2016 at 10:22 AM, Ian Cordasco <sigmavirus24 at 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).
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
> * 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.

+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-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



-- 
Emilien Macchi