

Ask HN: What Are Some Good GitHub "Contributing" Examples? - pessimism

With the addition of Contributing Guidelines[1], there is now a clear incentive to put your general and idiosyncratic guidelines into succinct prose.<p>I have written what I think is a good set of guidelines[2], but there is a chicken-and-egg problem in that I don’t really have the following to test it on; on the other hand, it might very well have discouraged some people from posting borderline-useless project feedback.<p>In addition, my Travis continuous integration also automatically vets the pull request code on a very, very basic level, which is something akin to a second layer of defence against bad contributions.<p>Where else are there some guidelines that could be instructive to learn from with direct application to a GitHub project? I don’t think community guidelines like those by pg are relevant here, especially in the spirit of brevity.<p>Perhaps we could look into creating a CONTRIBUTING Bootstrap as a default template for writing your GitHub contribution guidelines?<p>What are your experiences? Especially those of you with very popular projects that have to straddle a deluge of feedback and scale accordingly[3]?<p>[1]: https://github.com/blog/1184-contributing-guidelines<p>[2]: http://pygm.us/9uVqoDHQ<p>[3]: http://news.ycombinator.com/item?id=4820149
======
dunstenloopy
It took me ages that you mean a file called CONTRIBUTING at the root of your
project repository. It just looked like you were shouting.

------
pessimism
Clicky linky:

[1]: <https://github.com/blog/1184-contributing-guidelines>

[2]: <http://pygm.us/9uVqoDHQ>

[3]: <http://news.ycombinator.com/item?id=4820149>

------
vitovito
"Contributing" is a project by bradfitz specifically to explain how to
contribute to projects, and to collect those explanations.

<http://contributing.appspot.com/>

On Github at: <https://github.com/bradfitz/contributing>

------
th
CONTRIBUTING.md files in:

* [OpenGovernment][1]

* [Factory Girl][2]

* [agner][3]

* [suspenders][4]

[1]:
[https://github.com/opengovernment/opengovernment/blob/master...](https://github.com/opengovernment/opengovernment/blob/master/CONTRIBUTING.md)

[2]:
[https://github.com/thoughtbot/factory_girl_rails/blob/master...](https://github.com/thoughtbot/factory_girl_rails/blob/master/CONTRIBUTING.md)

[3]: <https://github.com/agner/agner/blob/master/CONTRIBUTING.md>

[4]:
[https://github.com/thoughtbot/suspenders/blob/master/CONTRIB...](https://github.com/thoughtbot/suspenders/blob/master/CONTRIBUTING.md)

------
notmyname
We just added a CONTRIBUTING file to OpenStack Swift (and I believe the other
OpenStack projects are getting one soon):
[https://github.com/openstack/swift/commit/fdf55c2817c9a457de...](https://github.com/openstack/swift/commit/fdf55c2817c9a457de4d5609cabfda0aa0620dc1).

The odd thing about OpenStack (from a GitHub perspective) is that the
OpenStack development process doesn't use GitHub's issues or pull requests.
This has been documented on the OpenStack wiki, but that info is now also in
our CONTRIBUTING file. Our file is an example of something to share with
potential contributors to point them in the right direction.

~~~
IanWhalen
notmyname's mention of their process does reinforce one of the difficulties
you'll have to address if you want to make a Bootstrap-like template - almost
every company has a _slightly_ different process.

OpenStack doesn't use GitHub for issues or pull requests, while MongoDB
doesn't use their issues but does use pull requests. Some projects require you
to sign a contributor agreement, some don't. Different languages (coding
standards), different platforms (testing), etc. So you'll probably want to
bake the customization aspect (a la
<http://twitter.github.com/bootstrap/customize.html>) into the very core of
your idea.

As for examples: \- the guidelines for the MongoDB project (not bad, I think)
are here:
[https://github.com/mongodb/mongo/blob/master/CONTRIBUTING.rs...](https://github.com/mongodb/mongo/blob/master/CONTRIBUTING.rst)
\- and the Contributor Guidelines for Chef are quite good too:
<http://wiki.opscode.com/display/chef/How+to+Contribute>

~~~
pessimism
I was thinking about something dynamic and interactive with dialogues like
“Does this apply to you?”, where people can click _Yes_ or _No_.

Because you are entirely right, and there will never be a one-size-fits-all
_file_. That’s why I am thinking about a solution that instead uses one-size-
fits-all _questions_ that people have to ask themselves, and these could
dynamically either create the guidelines outright or prompt the authors to
think about the question for themselves.

As my own guidelines highlight, you inevitably veer into subjective style
guidelines, and we all know how long people can go on endlessly about
JavaScript style guidelines.

------
robinho364
I support that "Perhaps we could look into creating a CONTRIBUTING Bootstrap
as a default template for writing your GitHub contribution guidelines". I am a
new developer who have been using github for only a few month. At the
beginning, I even don't know how to use the "git" to manage my repository. It
really takes me some days to learn it.

------
rizumu
This one is done well:
[http://opencomparison.readthedocs.org/en/latest/contributing...](http://opencomparison.readthedocs.org/en/latest/contributing.html)

~~~
pessimism
Some great guidelines in there. I added some to my own as a result.

Thinking over these guidelines, I think it could be useful to popular projects
to have a set of canned responses to different kinds of erroneous issues and
pull requests. They could also come with attacked action such as labelling and
the closing of the issue or pull request.

Although I guess this could be implemented through a browser extension, if the
people at GitHub don’t implement it.

