{"action":"created","issue":{"url":"https://api.github.com/repos/juttle/juttle/issues/104","labels_url":"https://api.github.com/repos/juttle/juttle/issues/104/labels{/name}","comments_url":"https://api.github.com/repos/juttle/juttle/issues/104/comments","events_url":"https://api.github.com/repos/juttle/juttle/issues/104/events","html_url":"https://github.com/juttle/juttle/pull/104","id":124857737,"number":104,"title":"Adding contributing guidelines","user":{"login":"dmehra","id":5817365,"avatar_url":"https://avatars.githubusercontent.com/u/5817365?v=3","gravatar_id":"","url":"https://api.github.com/users/dmehra","html_url":"https://github.com/dmehra","followers_url":"https://api.github.com/users/dmehra/followers","following_url":"https://api.github.com/users/dmehra/following{/other_user}","gists_url":"https://api.github.com/users/dmehra/gists{/gist_id}","starred_url":"https://api.github.com/users/dmehra/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/dmehra/subscriptions","organizations_url":"https://api.github.com/users/dmehra/orgs","repos_url":"https://api.github.com/users/dmehra/repos","events_url":"https://api.github.com/users/dmehra/events{/privacy}","received_events_url":"https://api.github.com/users/dmehra/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":2,"created_at":"2016-01-04T22:52:37Z","updated_at":"2016-01-05T13:50:30Z","closed_at":null,"pull_request":{"url":"https://api.github.com/repos/juttle/juttle/pulls/104","html_url":"https://github.com/juttle/juttle/pull/104","diff_url":"https://github.com/juttle/juttle/pull/104.diff","patch_url":"https://github.com/juttle/juttle/pull/104.patch"},"body":"resolves #99\r\n\r\nI used [puppet](https://github.com/puppetlabs/puppet/blob/master/CONTRIBUTING.md) and [atom](https://github.com/atom/atom/blob/master/CONTRIBUTING.md) docs as examples. The filename [CONTRIBUTING.md](https://github.com/blog/1184-contributing-guidelines) is standard.\r\n\r\nWe are missing something like a [CLA](https://en.wikipedia.org/wiki/Contributor_License_Agreement) or Certificate of origin like [nodejs](https://nodejs.org/en/get-involved/development/#developers-certificate-of-origin-10). It's not clear to me how critical is to have one, and must it be explicitly signed (using a tool like [clahub](https://www.clahub.com/) perhaps?) or is it enough to mention that by contributing, you allow to abide by the CLA.\r\n\r\n@mccanne @demmer @dmajda\r\n"},"comment":{"url":"https://api.github.com/repos/juttle/juttle/issues/comments/169005158","html_url":"https://github.com/juttle/juttle/pull/104#issuecomment-169005158","issue_url":"https://api.github.com/repos/juttle/juttle/issues/104","id":169005158,"user":{"login":"dmajda","id":18821,"avatar_url":"https://avatars.githubusercontent.com/u/18821?v=3","gravatar_id":"","url":"https://api.github.com/users/dmajda","html_url":"https://github.com/dmajda","followers_url":"https://api.github.com/users/dmajda/followers","following_url":"https://api.github.com/users/dmajda/following{/other_user}","gists_url":"https://api.github.com/users/dmajda/gists{/gist_id}","starred_url":"https://api.github.com/users/dmajda/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/dmajda/subscriptions","organizations_url":"https://api.github.com/users/dmajda/orgs","repos_url":"https://api.github.com/users/dmajda/repos","events_url":"https://api.github.com/users/dmajda/events{/privacy}","received_events_url":"https://api.github.com/users/dmajda/received_events","type":"User","site_admin":false},"created_at":"2016-01-05T13:50:30Z","updated_at":"2016-01-05T13:50:30Z","body":"TL;DR. Seriously.\r\n\r\nI totally appreciate the effort that went into this, but the contribution guidelines need to be really short, otherwise they will discourage contributions and people wouldn’t read them before opening an issue or a PR, which defeats their purpose.\r\n\r\nI think the main goals of the guidelines are:\r\n\r\n  * Help users to create meaningful bug reports and feature requests.\r\n  * Help developers to create good PRs.\r\n  * Direct anyone who needs a question answered or needs to get in touch with developers to the right place.\r\n\r\nIdeal guidelines would be a minimal document satisfying these goals. But the suggested guidelines are more of a comprehensive overview of our organization, development process, etc. Writing these things down is important, but IMO they should not be part of the guidelines. I’d much rather see something short & sweet, like [Nette guidelines](https://github.com/nette/http/blob/master/contributing.md). Another example is [YaST contribution guidelines](https://github.com/yast/yast-yast2/blob/master/CONTRIBUTING.md) I wrote some time ago (but there I would do several things differently today).\r\n\r\nSo, what about splitting some parts out of the guidelines as separate documents, putting them into the wiki, and just linking them? Beside shortening the guidelines, this would lead to less duplication (and later divergence) between `CONTRIBUTING.md` files in our various repos.\r\n\r\nI’d separate at least these documents:\r\n\r\n  * Project organization (mainly the repo descriptions)\r\n  * Development workflow (Waffle, issue lifecycle and labels used)\r\n\r\nAnd I’d structure the remaining content as:\r\n\r\n  * Asking questions\r\n  * Reporting bugs\r\n  * Requesting enhacements\r\n  * Contributing code\r\n\r\nI’d make these as short as possible (by moving all that can be moved to Development workflow and writing the content from the “minimum the external user needs to know to do X” perspective). Than decide whether these should stay in the guidelines or also be separated.\r\n\r\nIn any case, the result should be a document where the user who wants e.g. to file a bug quickly finds the relevant section, can read it quickly, and so the right thing. If interested, he can follow the links and read further on how we do things more generally.\r\n\r\n@dmehra @demmer Thoughts?"}}