|
| 1 | +# Contributing |
| 2 | + |
| 3 | +Thanks for your interest in helping out! Here are a **few** _weird_ tricks to |
| 4 | +~~cut your mortgage in half~~ maximize the global net efficiency of your efforts! |
| 5 | + |
| 6 | +## TL;DR: Checklist |
| 7 | + |
| 8 | +When opening an [issue](#issues): |
| 9 | +- [ ] search open/closed issues |
| 10 | +- [ ] discuss bug/enhancement in new or old issue |
| 11 | + |
| 12 | +[PR](#prs) time: |
| 13 | +- [ ] write tests |
| 14 | +- [ ] implement feature/fix bug |
| 15 | +- [ ] update docs |
| 16 | +- [ ] make a note in change log |
| 17 | + |
| 18 | +Remember, you don't need to do it all yourself; any of these are helpful! 😎 |
| 19 | + |
| 20 | +## Issues |
| 21 | + |
| 22 | +### Search open + closed issues for similar cases. |
| 23 | + |
| 24 | + You may find an open issue that closely matches what you are thinking. You |
| 25 | + may also find a closed issue with discussion that either solves your problem |
| 26 | + or explains why we are unlikely to solve it in the near future. |
| 27 | + |
| 28 | + If you find a matching issue that is open, and marked `accepted` and/or `help |
| 29 | + wanted`, you might want to [open a PR](#prs). |
| 30 | + |
| 31 | +### Open an issue. |
| 32 | + |
| 33 | + Let's discuss your issue. Could be as simple as unclear documentation or a |
| 34 | + wonky config file. |
| 35 | + If you're suggesting a feature, it might exist and need better |
| 36 | + documentation, or it might be in process. Even given those, some discussion might |
| 37 | + be warranted to ensure the enhancement is clear. |
| 38 | + |
| 39 | + You're welcome to jump right to a PR, but without a discussion, can't make any |
| 40 | + guarantees about merging. |
| 41 | + |
| 42 | + That said: sometimes seeing the code makes the discussion clearer.😄 |
| 43 | + |
| 44 | +This is a helpful contribution all by itself. Thanks! |
| 45 | + |
| 46 | +## PRs |
| 47 | + |
| 48 | +If you would like to implement something, firstly: thanks! Community contributions |
| 49 | +are a magical thing. Like Redux or [the flux capacitor](https://youtu.be/SR5BfQ4rEqQ?t=2m25s), |
| 50 | +they make open source possible. |
| 51 | + |
| 52 | +**Working on your first Pull Request?** |
| 53 | +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). |
| 54 | + |
| 55 | +Here are some things to keep in mind when working on a PR: |
| 56 | + |
| 57 | +#### Tests |
| 58 | + |
| 59 | +A PR that is just failing test cases for an existing issue is very helpful, as this |
| 60 | +can take as much time (if not more) as it takes to implement a new feature or fix |
| 61 | +a bug. |
| 62 | + |
| 63 | +If you only have enough time to write tests, fantastic! Submit away. This is a great |
| 64 | +jumping-off point for a core contributor or even another PR to continue what you've started. |
| 65 | + |
| 66 | +#### Docs |
| 67 | + |
| 68 | +For enhancements to rules, please update the docs in `docs/rules` matching the rule |
| 69 | +filename from `src/rules`. |
| 70 | + |
| 71 | +Also, take a quick look at the rule summary in [README.md] in case it could use tweaking, |
| 72 | +or add a line if you've implemented a new rule. |
| 73 | + |
| 74 | +Bugfixes may not warrant docs changes, though it's worth skimming the existing |
| 75 | +docs to see if there are any relevant caveats that need to be removed. |
| 76 | + |
| 77 | +#### Changelog |
| 78 | + |
| 79 | +Please add a quick blurb to the [**Unreleased**](./CHANGELOG.md#unreleased) section of the change log. Give yourself |
| 80 | +some credit, and please link back to the PR for future reference. This is especially |
| 81 | +helpful for resolver changes, as the resolvers are less frequently modified and published. |
| 82 | + |
| 83 | +Note also that the change log can't magically link back to Github entities (i.e. PRs, |
| 84 | +issues, users) or rules; there are a handful of footnote URL definitions at the bottom. |
| 85 | +You may need to add one or more URL if you've square-bracketed any such items. |
| 86 | + |
| 87 | +## Code of Conduct |
| 88 | + |
| 89 | +This is not so much a set of guidelines as a reference for what I hope may become |
| 90 | +a shared perspective on the project. I hope to write a longer essay to this end |
| 91 | +in the future. Comments are welcome, I'd like this to be as clear as possible. |
| 92 | + |
| 93 | +### Empathy |
| 94 | + |
| 95 | +People have feelings and perspectives, and people say and believe things for good reasons. |
| 96 | + |
| 97 | +If you find that you summarily disagree with a perspective stated by someone else, |
| 98 | +you likely each have histories that have moved you in opposite directions on a continuum |
| 99 | +that probably does not have a "wrong" or "right" end. It may be that you simply |
| 100 | +are working toward different goals that require different strategies. Every decision |
| 101 | +has pros and cons, and could result in some winners and some losers. It's great to |
| 102 | +discuss this so that both are well-known, and realize that even with infinite discussion, |
| 103 | +cons and losers will likely never go to zero. |
| 104 | + |
| 105 | +Also note that we're not doing brain surgery here, so while it's fine if we spend some time |
| 106 | +understanding each other, cordial disagreement should not be expensive in the |
| 107 | +long run, and we can accept that we will get some things wrong before we get them right (if ever!). |
| 108 | + |
| 109 | +If we can all get together behind the common goal of embracing empathy, everything else should be able to work itself out. |
| 110 | + |
| 111 | +#### Attribution |
| 112 | + |
| 113 | +Thanks for help from http://mozillascience.github.io/working-open-workshop/contributing/ |
| 114 | +for inspiration before I wrote this. --ben |
| 115 | + |
| 116 | +[README.md]: ./README.md |
0 commit comments