expand CONTRIBUTING.md; closes mochajs#2542 [ci skip]

Author: boneskull

CONTRIBUTING.md

@@ -1,49 +1,84 @@
 # Contributing to Mocha
 
-Hi!  We could use your help.  Let us help you help us.  Or something.
+> Please read these guidelines before submitting an issue, filing a feature request, or contributing code.
 
-## General
+## :question: Got a Question?
 
-1. If you are looking for a place to begin, **please send PRs for bugfixes instead of new features**, and/or **look for issues labeled `PR PLEASE`.**
+If you have a question about using Mocha, please use the [mailing list](https://groups.google.com/group/mochajs), [StackOverflow](https://stackoverflow.com), or ask the friendly people in our [chat room](https://gitter.im/mochajs/mocha).
 
-2.  **Help with documentation and the wiki is always appreciated**.
+## :bug: I Found a Bug
 
-3.  Please **be courteous and constructive** when commenting on issues, commits, and pull requests.
+Sorry!  It happens to the best of us.  If you've found a bug in Mocha, **please [search](https://github.com/mochajs/mocha/issues/) to see if it's already been reported**.  Otherwise, create a [new issue](https://github.com/mochajs/mocha/issues/new).  If you can fix the bug yourself, feel free to create a [pull request](#propose-a-change) thereafter.
 
-## Bug Reports & Issues
+Please include *as much detail as possible* to help us reproduce and diagnose the bug.  Most importantly:
 
-1.  When reporting a bug, please **provide steps to reproduce**.  If possible, show code.
-  
-2.  Please **show all code in JavaScript**.  We don't all read `<insert-language-that-compiles-to-JavaScript-here>`.  If you do not, you will be asked to.
+- Let us know *how* you're running Mocha (options, flags, environment, browser or Node.js, etc.)
+- Include your test code or file(s).  If large, please provide a link to a repository or [gist](https://gist.github.com).
+- Please show code in JavaScript only (any version)
 
-3.  Because Mocha works with many third-party libraries and tools, **ensure the bug you are reporting is actually within Mocha**.
+If we need more information from you, we'll let you know.  If you don't within a reasonable time frame (TBD), your issue will be automatically closed for inactivity.
 
-4.  If you report a bug, and it is inactive for a significant amount of time, it may be closed.  **Please respond promptly to requests for more information**.
+## :exclamation: Propose a Change
 
-## Pull Requests
+Before you get your hands dirty, please [search](https://github.com/mochajs/mocha/issues/) for a related issue, or [create a new one](https://github.com/mochajs/mocha/issues/new).  If you wish to contribute a new feature, this is doubly important!  Let's discuss your proposed changes first; we don't want you to waste time implementing a change that is at odds with the project's direction.  That said, we'll happily consider any contribution, no matter how great or small.
 
-1. Before sending a large PR, it's recommended to **create an issue to propose the change**.  Nobody wants to write a book of code and throw it away.
+*This paragraph would contain information about Mocha's roadmap, but it doesn't yet exist.* :poop:
 
-2.  Because Mocha should be kept as maintainable as possible, its codebase must be kept slim.  Historically, *most PRs for new features are not merged*.  New features inevitably increase the size of the codebase, and thus reduce maintainability.  Only features *deemed essential* are likely to be merged--this is at the discretion of the maintainer(s).  If your PR for a feature is not merged, this doesn't necessarily mean your PR was a bad idea, wouldn't be used, or otherwise sucks.  It just means **only essential PRs for new features are likely to be merged**. 
+It's also important to understand some overarching goals of Mocha, detailed below.
 
-3.  Due to the above, before creating a PR for a new feature, **create an issue to propose the feature.**
+### :soccer: About Project Goals
 
-4.  Please **respect existing coding conventions**, whatever those may be.
+Mocha is a test framework.  Developers use it against anything from legacy spaghetti in IE7 to stage-0 TC39 features in Electron.  While still staying current, Mocha will only drop support for old platforms as a last resort.  If and only if Mocha cannot move forward as a project, support will be dropped.  If workarounds exist, they are preferred.
 
-5.  If your PR has been waiting in limbo for some time, it's very helpful to **rebase against master**, which will make it easier to merge.
+Mocha adheres strictly to [semantic versioning](https://semver.org).  We are *extremely cautious* with changes that have the potential to break; given the size of Mocha's user base, it's *highly unlikely* a breaking change will slide by.
 
-6.  Please **add tests for new code**.
+Mocha's usage far outweighs its resources.  If a proposed feature would incur a maintenance penalty, it could be a hard sell.
 
-7.  **Always run `npm test` before sending a PR.**  If you break the tests, your PR will not be accepted until they are fixed.
+We ask you please keep these goals in mind when making or proposing changes.
 
-## Source Control
+### :shoe: Contributing Code: Step-by-Step
 
-1. Please **squash your commits** when sending a pull request.  If you are unfamiliar with this process, see [this guide](https://help.github.com/articles/about-git-rebase/).  If you have already pushed your changesets and are squashing thereafter, this may necessitate the use of a "force push".  Please [read the docs](http://git-scm.com/docs/git-push) before you attempt this. 
- 
-2. Please **follow the commit message conventions [outlined here](https://medium.com/code-adventures/git-conventions-a940ee20862d).**
+Follow these steps to get going.  If you are having trouble, don't be afraid to [ask for help](#got-a-question).
 
-## TL;DR
+1.  [Install Node.js 4.x or newer](https://nodejs.org/download).
+1.  Install [GNU Make](https://www.gnu.org/software/make/) or equivalent.
+1.  Follow [Github's documentation](https://help.github.com/articles/fork-a-repo/) on setting up Git, forking and cloning.
+1.  Create a new branch in your working copy.  Give your branch a descriptive name, such as `issue/12345`: `git checkout -b issue/12345`.
+1.  Execute `npm install` to install the development dependencies.
+1.  Make your changes and add them via `git add`.
+  - **Do not modify** the root `mocha.js` file directly; it is automatically generated.
+  - Your changes will likely be somewhere in `lib/`, `bin/` or `browser-entry.js` if your changes are browser-specific.
+  - Please add unit and/or integration tests (depending on the nature of your changes).
+  - Keep your PR focused.  Don't fix two things at once, or make formatting changes alongside bug fixes.
+1.  Before committing, run `npm test`.
+  - This will run unit tests, Node.js and browser integration tests, and lint the source code.
+  - The "browser" tests use Mocha to test itself; it will rebuild the root `mocha.js` file with your changes.
+  - **Please avoid committing changes to `mocha.js`**.
+  - Ultimately, your pull request will be built on our continuous integration servers ([Travis CI](https://travis-ci.org/mochajs/mocha) and [AppVeyor](https://ci.appveyor.com/project/boneskull/mocha)).  The first step to ensuring these checks pass is to test on your own machine.
+1.  Commit your changes.
+  - Use a brief message on the first line, referencing a relevant issue (e.g. `#12345`).
+  - Add detail in subsequent lines.
+1.  Push your changes to your fork.
+1.  Navigate to the source repository.  You should see a notification about your recent changes in your fork's branch, with a button to create a pull request.  Click it.
+1.  Describe your changes in detail here.  Once you're satisfied, submit the form.
+  - *PRO TIP*: If you've used a multi-line commit message, Github will pre-fill the PR's description with it.
+1.  If you have not signed our Contributor License Agreement, a friendly robot will prompt you to do so.  A CLA (electronic) signature is **required** for all contributions of code to Mocha.
+1.  CI will run against your changes.
+  - If the changes fail the checks, you will need to address those before merging.
+  - You don't need to make a new PR to make changes.  Instead, commit on top of your changes, and push these to your fork's branch.  The PR will be updated, and CI will re-run.
+  - Github will indicate if there's a conflict.  If this happens, you will need to [rebase](https://help.github.com/articles/about-git-rebase/) your branch onto the `master` branch of the source repository.  *Don't merge.*
+  - It's no longer necessary to "squash" your changes.
+1.  Be patient while your PR is reviewed.  This can take awhile ([why?](https://github.com/orgs/mochajs/projects/4)).  We may request changes; don't be afraid to question them.
 
-**Be kind, be diligent, look before you leap into a PR, and follow common community conventions**.
+## :angel: I Just Want To Help
 
-*- The Mocha Team*
+*Excellent.*  Here's how:
+
+- **Handy with JavaScript?**  Please check out the issues labeled [`pr-please`](https://git.io/vXYu2).
+- **Can you write good (and do other stuff good too)?**  Help with the documentation.  See the [issues for our site](https://github.com/mochajs/mochajs.github.io/issues).
+- **Design your thing?**  [Our site](https://github.com/mochajs/mochajs.github.io) needs your magic touch.
+- **Know Mocha's codebase?**  We could use your help triaging issues and/or reviewing pull requests.  Please contact an [org member](https://github.com/mochajs/people), and we'll chat.
+- **Want to build our community?**  Mocha has a *lot* of users.  We could use your help bringing everyone together in peace and harmony.  Please contact an [org member](https://github.com/mochajs/people).
+- **You can sell dirt to worms?**  Let's raise Mocha's profile in the JavaScript and OSS communities.  Please contact an [org member](https://github.com/mochajs/people)!
+- **Wait--you write unit tests for *fun*?**  A PR which increases coverage is unlikely to be turned down.
+- **Are you experienced?**  If you're a seasoned Mocha user, why not help answer some questions in the [chat room](https://gitter.im/mochajs/mocha)?