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-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
-- @flaper87 Flavio Percoco
signature.asc
Description: PGP signature
__________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
