From be18696c63d8abfef80e969b53a8dcb07c0e8da3 Mon Sep 17 00:00:00 2001 From: Ben Mosher Date: Fri, 22 Apr 2016 14:46:15 -0400 Subject: [PATCH 1/2] first draft of CONTRIBUTING.md --- CONTRIBUTING.md | 109 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..9b4447db76 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,109 @@ +# Contributing + +Thanks for your interest in helping out! Here are a **few** _weird_ tricks to +~~cut your mortgage in half~~ maximize the global net efficiency of your efforts! + +## Issues + +### Search open + closed issues for similar cases. + + You may find an open issue that closely matches what you are thinking. You + may also find a closed issue with discussion that either solves your problem + or explains why we are unlikely to solve it in the near future. + + If you find a matching issue that is open, and marked `accepted` and/or `help + wanted`, you might want to [open a PR](#prs). + +### Open an issue. + + Let's discuss your issue. Could be as simple as unclear documentation or a + wonky config file. + If you're suggesting a feature, it might exist and need better + documentation, or it might be in process. Even given those, some discussion might + be warranted to ensure the enhancement is clear. + + You're welcome to jump right to a PR, but without a discussion, can't make any + guarantees about merging. + + That said: sometimes seeing the code makes the discussion clearer.😄 + +This is a helpful contribution all by itself. Thanks! + +## PRs + +If you would like to implement something, firstly: thanks! Community contributions +are a magical thing. Like Redux or the flux capacitor, they make open source possible. + +Here are some things to keep in mind when working on a PR: + +#### Tests + +A PR that is just failing test cases for an existing issue is very helpful, as this +can take as much time (if not more) as it takes to implement a new feature or fix +a bug. + +If you only have enough time to write tests, fantastic! Submit away. This is a great +jumping-off point for a core contributor or even another PR to continue what you've started. + +#### Docs + +For enhancements to rules, please update the docs in `docs/rules` matching the rule +filename from `src/rules`. + +Also, take a quick look at the rule summary in README.md in case it could use tweaking, +or add a line if you've implemented a new rule. + +Bugfixes may not warrant docs changes, though it's worth skimming the existing +docs to see if there are any relevant caveats that need to be removed. + +#### Changelog + +Please add a quick blurb to the [**Unreleased**](./CHANGELOG.md#unreleased) section of the change log. Give yourself +some credit, and please link back to the PR for future reference. This is especially +helpful for resolver changes, as the resolvers are less frequently modified and published. + +Note also that the change log can't magically link back to Github entities (i.e. PRs, +issues, users) or rules; there are a handful of footnote URL definitions at the bottom. +You may need to add one or more URL if you've square-bracketed any such items. + +## Checklist + +- [ ] search open/closed issues +- [ ] discuss bug/enhancement in new or old issue + +PR time: +- [ ] write tests +- [ ] implement feature/fix bug +- [ ] update docs +- [ ] make a note in change log + +Remember, you don't need to do it all yourself; any of these are helpful! 😎 + +## Code of Conduct + +This is not so much a set of guidelines as a reference for what I hope may become +a shared perspective on the project. I hope to write a longer essay to this end +in the future. Comments are welcome, I'd like this to be as clear as possible. + +### Empathy + +People have feelings and perspectives, and people say and believe things for good reasons. + +If you find that you summarily disagree with a perspective stated by someone else, +you likely each have histories that have moved you in opposite directions on a continuum +that probably does not have a "wrong" or "right" end. It may be that you simply +are working toward different goals that require different strategies. Every decision +has pros and cons, and could result in some winners and some losers. It's great to +discuss this so that both are well-known, and realize that even with infinite discussion, +cons and losers will likely never go to zero. + +Also note that we're not doing brain surgery here, so while it's fine if we spend some time +understanding each other, cordial disagreement should not be expensive in the +long run, and we can accept that we will get some things wrong before we get them right (if ever!). + +If we can all get together behind the common goal of embracing empathy, everything else should be able to work itself out. + +#### Attribution + +Thanks for help from http://mozillascience.github.io/working-open-workshop/contributing/ +for inspiration before I wrote this. --ben From 3baa13e680a08cd2bdad489773232b50243ef21f Mon Sep 17 00:00:00 2001 From: Ben Mosher Date: Mon, 9 May 2016 07:13:10 -0400 Subject: [PATCH 2/2] feedback'd: - added link to @kentcdodd's contributing how-to course - moved checklist to the top --- CONTRIBUTING.md | 37 ++++++++++++++++++++++--------------- 1 file changed, 22 insertions(+), 15 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9b4447db76..35a6b14b57 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,6 +3,20 @@ Thanks for your interest in helping out! Here are a **few** _weird_ tricks to ~~cut your mortgage in half~~ maximize the global net efficiency of your efforts! +## TL;DR: Checklist + +When opening an [issue](#issues): +- [ ] search open/closed issues +- [ ] discuss bug/enhancement in new or old issue + +[PR](#prs) time: +- [ ] write tests +- [ ] implement feature/fix bug +- [ ] update docs +- [ ] make a note in change log + +Remember, you don't need to do it all yourself; any of these are helpful! 😎 + ## Issues ### Search open + closed issues for similar cases. @@ -32,7 +46,11 @@ This is a helpful contribution all by itself. Thanks! ## PRs If you would like to implement something, firstly: thanks! Community contributions -are a magical thing. Like Redux or the flux capacitor, they make open source possible. +are a magical thing. Like Redux or [the flux capacitor](https://youtu.be/SR5BfQ4rEqQ?t=2m25s), +they make open source possible. + +**Working on your first Pull Request?** +You can learn how from this _free_ series [How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github). Here are some things to keep in mind when working on a PR: @@ -50,7 +68,7 @@ jumping-off point for a core contributor or even another PR to continue what you For enhancements to rules, please update the docs in `docs/rules` matching the rule filename from `src/rules`. -Also, take a quick look at the rule summary in README.md in case it could use tweaking, +Also, take a quick look at the rule summary in [README.md] in case it could use tweaking, or add a line if you've implemented a new rule. Bugfixes may not warrant docs changes, though it's worth skimming the existing @@ -66,19 +84,6 @@ Note also that the change log can't magically link back to Github entities (i.e. issues, users) or rules; there are a handful of footnote URL definitions at the bottom. You may need to add one or more URL if you've square-bracketed any such items. -## Checklist - -- [ ] search open/closed issues -- [ ] discuss bug/enhancement in new or old issue - -PR time: -- [ ] write tests -- [ ] implement feature/fix bug -- [ ] update docs -- [ ] make a note in change log - -Remember, you don't need to do it all yourself; any of these are helpful! 😎 - ## Code of Conduct This is not so much a set of guidelines as a reference for what I hope may become @@ -107,3 +112,5 @@ If we can all get together behind the common goal of embracing empathy, everythi Thanks for help from http://mozillascience.github.io/working-open-workshop/contributing/ for inspiration before I wrote this. --ben + +[README.md]: ./README.md