Open Stack

On 21/12/16 07:22 -0800, 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]
>
>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.
>

So, I'd even take it a step further. Standardizing the README files wouldn't
hurt either. I'm not suggesting that the entire README file should be the same
for everyone but we could have a common header/top sections for every project.

I recently hit this issue when submitting patches to add badges to the README
file and, understandably, some projects weren't too happy with how the top title
section looked like. If we can make this a simple community goal, I believe it'd
be valuable.

Recardless of whether the README and HACKING files are rendered, I believe some
consistency across repos would be great. I look at README files on cloned repos
too, I don't use GH to read these files if I already have them locally.

Flavio


>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

-- 
@flaper87
Flavio Percoco
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 862 bytes
Desc: not available
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20161222/34240838/attachment.pgp>