Open Stack

Hi stackers!

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>
> 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".
If CONTRIBUTING.rst is widely used and it can help newcomers, I'm for
adding it.


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


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



-- 
Best regards,
Andrey Kurilin.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20161221/8b6c07d2/attachment.html>