| OLD | NEW |
| (Empty) | |
| 1 # Contributing to Mocha |
| 2 |
| 3 > Please read these guidelines before submitting an issue, filing a feature requ
est, or contributing code. |
| 4 |
| 5 ## :question: Got a Question? |
| 6 |
| 7 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). |
| 8 |
| 9 ## :bug: I Found a Bug |
| 10 |
| 11 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 r
eported**. Otherwise, create a [new issue](https://github.com/mochajs/mocha/iss
ues/new). If you can fix the bug yourself, feel free to create a [pull request]
(#propose-a-change) thereafter. |
| 12 |
| 13 Please include *as much detail as possible* to help us reproduce and diagnose th
e bug. Most importantly: |
| 14 |
| 15 - Let us know *how* you're running Mocha (options, flags, environment, browser o
r Node.js, etc.) |
| 16 - Include your test code or file(s). If large, please provide a link to a repos
itory or [gist](https://gist.github.com). |
| 17 - Please show code in JavaScript only (any version) |
| 18 |
| 19 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 inacti
vity. |
| 20 |
| 21 ## :exclamation: Propose a Change |
| 22 |
| 23 Before you get your hands dirty, please [search](https://github.com/mochajs/moch
a/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 imp
ortant! Let's discuss your proposed changes first; we don't want you to waste t
ime implementing a change that is at odds with the project's direction. That sa
id, we'll happily consider any contribution, no matter how great or small. |
| 24 |
| 25 *This paragraph would contain information about Mocha's roadmap, but it doesn't
yet exist.* :poop: |
| 26 |
| 27 It's also important to understand some overarching goals of Mocha, detailed belo
w. |
| 28 |
| 29 ### :soccer: About Project Goals |
| 30 |
| 31 Mocha is a test framework. Developers use it against anything from legacy spagh
etti 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 workaround
s exist, they are preferred. |
| 32 |
| 33 Mocha adheres strictly to [semantic versioning](https://semver.org). We are *ex
tremely 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. |
| 34 |
| 35 Mocha's usage far outweighs its resources. If a proposed feature would incur a
maintenance penalty, it could be a hard sell. |
| 36 |
| 37 We ask you please keep these goals in mind when making or proposing changes. |
| 38 |
| 39 ### :shoe: Contributing Code: Step-by-Step |
| 40 |
| 41 Follow these steps to get going. If you are having trouble, don't be afraid to
[ask for help](#got-a-question). |
| 42 |
| 43 1. [Install Node.js 4.x or newer](https://nodejs.org/download). |
| 44 1. Install [GNU Make](https://www.gnu.org/software/make/) or equivalent. |
| 45 1. Follow [Github's documentation](https://help.github.com/articles/fork-a-repo
/) on setting up Git, forking and cloning. |
| 46 1. Create a new branch in your working copy. Give your branch a descriptive na
me, such as `issue/12345`: `git checkout -b issue/12345`. |
| 47 1. Execute `npm install` to install the development dependencies. |
| 48 1. Make your changes and add them via `git add`. |
| 49 - **Do not modify** the root `mocha.js` file directly; it is automatically gen
erated. |
| 50 - Your changes will likely be somewhere in `lib/`, `bin/` or `browser-entry.js
` if your changes are browser-specific. |
| 51 - Please add unit and/or integration tests (depending on the nature of your ch
anges). |
| 52 - Keep your PR focused. Don't fix two things at once, or make formatting chan
ges alongside bug fixes. |
| 53 1. Before committing, run `npm test`. |
| 54 - This will run unit tests, Node.js and browser integration tests, and lint th
e source code. |
| 55 - The "browser" tests use Mocha to test itself; it will rebuild the root `moch
a.js` file with your changes. |
| 56 - **Please avoid committing changes to `mocha.js`**. |
| 57 - Ultimately, your pull request will be built on our continuous integration se
rvers ([Travis CI](https://travis-ci.org/mochajs/mocha) and [AppVeyor](https://c
i.appveyor.com/project/boneskull/mocha)). The first step to ensuring these chec
ks pass is to test on your own machine. |
| 58 1. Commit your changes. |
| 59 - Use a brief message on the first line, referencing a relevant issue (e.g. `#
12345`). |
| 60 - Add detail in subsequent lines. |
| 61 1. Push your changes to your fork. |
| 62 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. |
| 63 1. Describe your changes in detail here. Once you're satisfied, submit the for
m. |
| 64 - *PRO TIP*: If you've used a multi-line commit message, Github will pre-fill
the PR's description with it. |
| 65 1. If you have not signed our Contributor License Agreement, a friendly robot w
ill prompt you to do so. A CLA (electronic) signature is **required** for all c
ontributions of code to Mocha. |
| 66 1. CI will run against your changes. |
| 67 - If the changes fail the checks, you will need to address those before mergin
g. |
| 68 - 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. |
| 69 - 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.* |
| 70 - It's no longer necessary to "squash" your changes. |
| 71 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 t
o question them. |
| 72 |
| 73 ## :angel: I Just Want To Help |
| 74 |
| 75 *Excellent.* Here's how: |
| 76 |
| 77 - **Handy with JavaScript?** Please check out the issues labeled [`pr-please`](
https://git.io/vXYu2). |
| 78 - **Can you write good (and do other stuff good too)?** Help with the documenta
tion. See the [issues for our site](https://github.com/mochajs/mochajs.github.i
o/issues). |
| 79 - **Design your thing?** [Our site](https://github.com/mochajs/mochajs.github.i
o) needs your magic touch. |
| 80 - **Know Mocha's codebase?** We could use your help triaging issues and/or revi
ewing pull requests. Please contact an [org member](https://github.com/orgs/moc
hajs/people), and we'll chat. |
| 81 - **Want to build our community?** Mocha has a *lot* of users. We could use yo
ur help bringing everyone together in peace and harmony. Please contact an [org
member](https://github.com/mochajs/people). |
| 82 - **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)! |
| 83 - **Wait--you write unit tests for *fun*?** A PR which increases coverage is un
likely to be turned down. |
| 84 - **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)? |
| OLD | NEW |