Thanks to visit codestin.com
Credit goes to github.com

Skip to content

docs: Cleanup CONTRIBUTING.md and DEVELOPMENT.md #5538

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mark-wiemer wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: Cleanup CONTRIBUTING.md and DEVELOPMENT.md #5538

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
87c959a
Cleanup CONTRIBUTING.md and DEVELOPMENT.md
mark-wiemer Nov 21, 2025
a9c4f77
Merge branch 'main' into issue-5537
mark-wiemer Nov 21, 2025
ff01ad2
Update .github/CONTRIBUTING.md
mark-wiemer Dec 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 3 additions & 60 deletions .github/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,65 +72,8 @@ _Excellent._ Here's how:
- **Do 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 [our Discord's `#help` channel](https://discord.gg/KeDn2uXhER)?

## 👞 Contributing Code: Step-by-Step

First follow the steps in [DEVELOPMENT.md](./DEVELOPMENT.md) to get Mocha's repository installed locally.
Then:

### 🎋 Initial Creation

1. Make sure the issue is labeled with [`status: accepting prs`](https://github.com/mochajs/mocha/issues?q=is%3Aissue+is%3Aopen+label%3A%22status%3A+accepting+prs%22)
1. Create a new branch in your working copy.
1. Make your changes and add them via `git add`.
- Your changes will likely be somewhere in `lib/`, `bin/`, or (if your changes are browser-specific) `browser-entry.js`.
- Unit and/or integration **tests are required** for any code change.
These live in `test/`.
- **Do not modify** the root `mocha.js` file directly; it is automatically generated.
- Keep your PR focused.
Don't fix two things at once; don't upgrade dependencies unless necessary.
1. Before committing, run `npm test`.
- This will run both Node.js-based and browser-based tests.
- Ultimately, your pull request will be built on our continuous integration servers ([GitHub Actions](https://github.com/mochajs/mocha/actions?query=workflow%3A%22Tests%22)).
The first step to ensuring these checks pass is to test on your own machine.
- When tests are run in CI, a coverage check is sent to [Codecov](https://app.codecov.io/gh/mochajs/mocha). You'll need to [add the Codecov GitHub app](https://app.codecov.io/login) to upload these results from your fork. This is recommended but not necessary to open a PR.
**A drop in code coverage % is considered a failed check**.
1. Commit your changes.
- Use a brief message on the first line, referencing a relevant issue (e.g. `closes #12345`).
- Add detail in subsequent lines.
- A pre-commit hook will run which automatically formats your staged changes (and fixes any problems it can) with ESLint and Prettier.
If ESLint fails to fix an issue, your commit will fail and you will need to manually correct the problem.
1. <a name="up-to-date"/> (Optional) Ensure you are up-to-date with Mocha's `main` branch:
- You can add an "upstream" remote repo using `git remote add upstream https://github.com/mochajs/mocha.git && git fetch upstream`.
- Navigate to your `main` branch using `git checkout main`.
- Pull changes from `upstream` using `git pull upstream main`.
- If any changes were pulled in, update your branch from `main` by switching back to your branch (`git checkout <your-branch>`) then merging using `git merge main`.
1. Push your changes to your fork; `git push origin`.
1. In your browser, navigate to [mochajs/mocha](https://github.com/mochajs/mocha).
You should see a notification about your recent changes in your fork's branch, with a (green?) button to create a pull request.
Click it.
1. Describe your changes in detail here, following the template.
Once you're satisfied, submit the form.

At that point, hooray! 🎉
You should see a pull request on github.com/mochajs/mocha/pulls.

### 🏭 PR Process

Now that the pull request exists, some tasks will be run on it:

1. If you have not signed our [Contributor License Agreement](https://js.foundation/cla), a friendly robot will prompt you to do so.
A [CLA](https://cla.js.foundation/mochajs/mocha) (electronic) signature is **required** for all contributions of code to Mocha.
1. Continuous integration checks will run against your changes.
The result of these checks will be displayed on your PR.
- If the checks fail, you must address those before the PR is accepted.
1. Be patient while your PR is reviewed.
This can take a while.
We may request changes, but don't be afraid to question them.
1. Your PR might become conflicted with the code in `main`.
If this is the case, you will need to [update your PR](#up-to-date) and resolve your conflicts.
1. You don't need to make a new PR to any needed 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.
1. Once you've addressed all the feedback you can, [re-request review on GitHub](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews#re-requesting-a-review).
## 👞 Contributing Code

[DEVELOPMENT.md](./DEVELOPMENT.md) has detailed steps for writing code for Mocha 🙂

Join us in [our Discord](https://discord.gg/KeDn2uXhER)!
131 changes: 97 additions & 34 deletions .github/DEVELOPMENT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,43 +5,106 @@ If you are having trouble, don't be afraid to [ask for help](./CONTRIBUTING.md#

## Prerequisites

- [Install Node.js 14 LTS or newer with npm@7+](https://nodejs.org/en/download).
- If you're new to installing Node, a tool like [nvm](https://github.com/nvm-sh/nvm#install-script) can help you manage multiple version installations.
- You will need [Google Chrome](https://www.google.com/chrome) to run browser-based tests locally.
- If you're fixing an issue, make sure it's labeled with [`status: accepting prs`](https://github.com/mochajs/mocha/issues?q=is%3Aissue+is%3Aopen+label%3A%22status%3A+accepting+prs%22)
- [Install the current Node.js LTS](https://nodejs.org/en/download)
- [Install Google Chrome](https://www.google.com/chrome) if you want to run browser-based tests locally

## Setup

1. Follow [Github's documentation](https://help.github.com/articles/fork-a-repo) on setting up Git, forking, and cloning.
1. Execute `npm install` to install the development dependencies.
- Do not use `yarn install` or `pnpm install`.
- Some optional dependencies may fail; you can safely ignore these unless you are trying to build the documentation.
- If you're sick of seeing the failures, run `npm install --ignore-scripts`.

## Developing Mocha

When you contribute to Mocha, you will probably want to try to run your changes on the test suite of another project. You can (and should) run the test suite of Mocha itself before committing, but also confirming that your changes give the expected result on another project.

For example, [WebSocket.io](https://github.com/LearnBoost/websocket.io/):

$ git clone https://github.com/LearnBoost/websocket.io.git

Retrieve websocket.io's dependencies, which will include the stable version of Mocha:

$ cd websocket.io/
$ npm install

Replace the Mocha dependency by the current git repository:

$ cd node_modules/
$ mv mocha/ mocha.save
$ git clone https://github.com/mochajs/mocha.git

Install Mocha's dependencies for the development version:

$ cd mocha
$ npm install

Run websocket.io's test suite using the development version you just installed:

$ cd ../..
$ ./node_modules/.bin/mocha
1. Create a new branch in your working copy.

## Reproducing issues

We recommend creating a folder named `sandbox` within this repo, and then using a child project within `sandbox` for each issue you want to repro.
Copy link
Member

@JoshuaKGoldberg JoshuaKGoldberg Dec 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I actually have a different repro flow. I keep a folder at ~/repos/repros as a sibling to ~/repos/mocha. It's a Git repo with a branch for each test case / reproduction. The publicly interesting ones get pushed to https://github.com/JoshuaKGoldberg/repros.

Alternately, sometimes I use ~/repos/mocha-examples to get starting reproductions. It's pretty handy.

I don't think we should recommend such a specific usage flow. Not every user is going to want this.

Proposal: how about making this more general, like saying having some folder somewhere?


`package.json` will have a reference to the local Mocha build and any options you need for your repro.
We recommend [`cross-env`](https://www.npmjs.com/package/cross-env) for applying the `DEBUG` environment variable to get detailed logs (via the [`debug`](https://www.npmjs.com/package/debug) package).
Copy link
Member

@JoshuaKGoldberg JoshuaKGoldberg Dec 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cross-env is only useful if you're on Windows. If you're on Mac or Linux then you can omit it.

Use `--no-config` to avoid using the sample configs in this repo:

```jsonc
// package.json
{
"scripts": {
"debug-test": "cross-env DEBUG=* npm test",
"test": "mocha --no-config my.test.js",
},
"dependencies": {
"mocha": "file:../../",
},
"devDependencies": {
"cross-env": "^10.1.0",
},
}
```

You can create `my.test.js` as a sibling to `package.json`:

```js
// my.test.js
describe("hello", () => {
it("world", () => {
return true;
});
});
```

Then `npm test` will run the local version of mocha against the test that you wrote.

Once you've reproduced the bad behavior, you can get to work on fixing it!

## Opening a PR

1. Add your changes via `git add`.
- Your changes will likely be somewhere in `lib/`, `bin/`, or (if your changes are browser-specific) `browser-entry.js`.
- Unit and/or integration **tests are required** for any code change.
These live in `test/`.
- **Do not modify** the root `mocha.js` file directly; it is automatically generated.
- Keep your PR focused.
Don't fix two things at once; don't upgrade dependencies unless necessary.
1. Before committing, run `npm test`.
- This will run both Node.js-based and browser-based tests.
- Ultimately, your pull request will be built on our continuous integration servers ([GitHub Actions](https://github.com/mochajs/mocha/actions?query=workflow%3A%22Tests%22)).
The first step to ensuring these checks pass is to test on your own machine.
- When tests are run in CI, a coverage check is sent to [Codecov](https://app.codecov.io/gh/mochajs/mocha). You'll need to [add the Codecov GitHub app](https://app.codecov.io/login) to upload these results from your fork. This is recommended but not necessary to open a PR.
**A drop in code coverage % is considered a failed check**.
1. Commit your changes.
- Use a brief message on the first line, referencing a relevant issue (e.g. `closes #12345`).
- Add detail in subsequent lines.
- A pre-commit hook will run which automatically formats your staged changes (and fixes any problems it can) with ESLint and Prettier.
If ESLint fails to fix an issue, your commit will fail and you will need to manually correct the problem.
1. <a name="up-to-date"/> (Optional) Ensure you are up-to-date with Mocha's `main` branch:
- You can add an "upstream" remote repo using `git remote add upstream https://github.com/mochajs/mocha.git && git fetch upstream`.
- Navigate to your `main` branch using `git checkout main`.
- Pull changes from `upstream` using `git pull upstream main`.
- If any changes were pulled in, update your branch from `main` by switching back to your branch (`git checkout <your-branch>`) then merging using `git merge main`.
1. Push your changes to your fork; `git push origin`.
1. In your browser, navigate to [mochajs/mocha](https://github.com/mochajs/mocha).
You should see a notification about your recent changes in your fork's branch, with a (green?) button to create a pull request.
Click it.
1. Describe your changes in detail here, following the template.
Once you're satisfied, submit the form.

At that point, hooray! 🎉
You should see a pull request on github.com/mochajs/mocha/pulls.

## PR review process

Now that the pull request exists, some tasks will be run on it:

1. If you have not signed our [Contributor License Agreement](https://js.foundation/cla), a friendly robot will prompt you to do so.
A [CLA](https://cla.js.foundation/mochajs/mocha) (electronic) signature is **required** for all contributions of code to Mocha.
1. Continuous integration checks will run against your changes.
The result of these checks will be displayed on your PR.
- If the checks fail, you must address those before the PR is accepted.
1. Be patient while your PR is reviewed.
This can take a while.
We may request changes, but don't be afraid to question them.
1. Your PR might become conflicted with the code in `main`.
If this is the case, you will need to [update your PR](#up-to-date) and resolve your conflicts.
1. You don't need to make a new PR to any needed 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.
1. Once you've addressed all the feedback you can, [re-request review on GitHub](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews#re-requesting-a-review).