From 06ea75d52667e5b1861c70b9cc4f779de899ef8e Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Sat, 2 Dec 2023 10:24:17 -0500 Subject: [PATCH 1/7] docs: overhaul contributing and maintenance docs for end-of-year 2023 --- .github/CODE_OF_CONDUCT.md | 75 ++--- .github/CONTRIBUTING.md | 151 ++++++---- .github/DEVELOPMENT.md | 20 ++ .github/ISSUE_TEMPLATE/01-bug.yml | 45 +++ .github/ISSUE_TEMPLATE/02-documentation.yml | 25 ++ .github/ISSUE_TEMPLATE/03-feature-request.yml | 37 +++ .../ISSUE_TEMPLATE/04-repository-tooling.yml | 29 ++ .github/ISSUE_TEMPLATE/bug_report.md | 68 ----- .github/ISSUE_TEMPLATE/config.yml | 14 + .github/ISSUE_TEMPLATE/feature_request.md | 18 -- .github/ISSUE_TEMPLATE/support-question.md | 15 - .github/PULL_REQUEST_TEMPLATE.md | 45 +-- MAINTAINERS.md | 280 +++++++++++------- README.md | 10 +- 14 files changed, 494 insertions(+), 338 deletions(-) create mode 100644 .github/DEVELOPMENT.md create mode 100644 .github/ISSUE_TEMPLATE/01-bug.yml create mode 100644 .github/ISSUE_TEMPLATE/02-documentation.yml create mode 100644 .github/ISSUE_TEMPLATE/03-feature-request.yml create mode 100644 .github/ISSUE_TEMPLATE/04-repository-tooling.yml delete mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/config.yml delete mode 100644 .github/ISSUE_TEMPLATE/feature_request.md delete mode 100644 .github/ISSUE_TEMPLATE/support-question.md diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md index 1d08ae277e..93aef1d0cf 100644 --- a/.github/CODE_OF_CONDUCT.md +++ b/.github/CODE_OF_CONDUCT.md @@ -3,35 +3,36 @@ ## Be friendly and patient We understand that everyone has different levels of experience or knowledge in many diverse fields, be it technical or -non-technical in nature. We also have areas of knowledge we are eager to expand; we want to be a community where people -can not only contribute, but feel comfortable to ask questions as well and learn along the way. If someone says something -wrong, or says something accidentally offensive, respond with patience and try to keep it polite and civil. Remember that -we all were newbies at one point. +non-technical in nature. +We also have areas of knowledge we are eager to expand; we want to be a community where people can not only contribute, but feel comfortable to ask questions as well and learn along the way. +If someone says something wrong, or says something accidentally offensive, respond with patience and try to keep it polite and civil. +Remember that we all were newbies at one point. ## Be welcoming -We strive to be a community that welcomes and supports people of all backgrounds and identities. This includes, but is not -limited to, members of any race, ethnicity, culture, national origin, color, immigration status, social and economic class, -educational level, sex, sexual orientation, gender identity and expression, age, size, family status, political belief, -religion, and mental and physical ability. +We strive to be a community that welcomes and supports people of all backgrounds and identities. +This includes, but is not limited to, members of any race, ethnicity, culture, national origin, color, immigration status, social and economic class, educational level, sex, sexual orientation, gender identity and expression, age, size, family status, political belief, religion, and mental and physical ability. ## Be considerate -Your work will be used by other people, and you in turn will depend on the work of others. Any decision you make will affect -users and colleagues, and you should take those consequences into account when making decisions. Remember that we’re a world-wide -community, so you might not be communicating in someone else’s primary language. +Your work will be used by other people, and you in turn will depend on the work of others. +Any decision you make will affect users and colleagues, and you should take those consequences into account when making decisions. +Remember that we’re a world-wide community, so you might not be communicating in someone else’s primary language. ## Be respectful -Not all of us will agree all the time, but disagreement is no excuse for poor behavior and poor manners. We might all -experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It’s important -to remember that a community where people feel uncomfortable or threatened is not a productive one. Members of the JS Foundation -community should be respectful when dealing with other members as well as with people outside the JS Foundation community. +Not all of us will agree all the time, but disagreement is no excuse for poor behavior and poor manners. +We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. +It’s important to remember that a community where people feel uncomfortable or threatened is not a productive one. +Members of the OpenJS Foundation community should be respectful when dealing with other members as well as with people outside the OpenJS Foundation community. ## Be careful in the words that you choose -We are a community of professionals, and we conduct ourselves professionally. Be kind to others. Do not insult or put -down other participants. Harassment and other exclusionary behavior aren’t acceptable. This includes, but is not limited to: +We are a community of professionals, and we conduct ourselves professionally. +Be kind to others. +Do not insult or put down other participants. +Harassment and other exclusionary behavior aren’t acceptable. +This includes, but is not limited to: - Violent threats or language directed against another person. - Discriminatory jokes and language. @@ -40,31 +41,34 @@ down other participants. Harassment and other exclusionary behavior aren’t acc - Personal insults, especially those using racist or sexist terms. - Unwelcome sexual attention. - Advocating for, or encouraging, any of the above behavior. -- Repeated harassment of others. In general, if someone asks you to stop, then stop. +- Repeated harassment of others. + In general, if someone asks you to stop, then stop. ## When we disagree, try to understand why -Disagreements, both social and technical, happen all the time and JS Foundation projects are no exception. It is important -that we resolve disagreements and differing views constructively. Remember that we’re different. The strength of the JS -Foundation comes from its varied community, people from a wide range of backgrounds. Different people have different -perspectives on issues. Being unable to understand why someone holds a viewpoint doesn’t mean that they’re wrong. Don’t -forget that it is human to err and blaming each other doesn’t get us anywhere. Instead, focus on helping to resolve issues -and learning from mistakes. +Disagreements, both social and technical, happen all the time and OpenJS Foundation projects are no exception. +It is important that we resolve disagreements and differing views constructively. +Remember that we’re different. +The strength of the OpenJS Foundation comes from its varied community, people from a wide range of backgrounds. +Different people have different perspectives on issues. +Being unable to understand why someone holds a viewpoint doesn’t mean that they’re wrong. +Don’t forget that it is human to err and blaming each other doesn’t get us anywhere. +Instead, focus on helping to resolve issues and learning from mistakes. Original text courtesy of the Speak Up! project and Django Project. ## QUESTIONS? -If you have questions, please see the FAQ. If that doesn’t answer your questions, feel free to email report@lists.openjsf.org. +If you have questions, please see the FAQ. +If that doesn’t answer your questions, feel free to email report@lists.openjsf.org. # OpenJS Foundation Code of Conduct -The OpenJS Foundation and its member projects use the Contributor -Covenant v1.4.1 as its Code of Conduct. Refer to the following -for the full text: +The OpenJS Foundation and its member projects use the Contributor Covenant v1.4.1 as its Code of Conduct. +Refer to the following for the full text: -- [english](https://www.contributor-covenant.org/version/1/4/code-of-conduct) -- [translations](https://www.contributor-covenant.org/translations) +- [Contributor Covenant v1.4.1 in english](https://www.contributor-covenant.org/version/1/4/code-of-conduct) +- [Contributor Covenant v1.4.1 translations](https://www.contributor-covenant.org/translations) Refer to the section on reporting and escalation in this document for the specific emails that can be used to report and escalate issues. @@ -72,7 +76,9 @@ Refer to the section on reporting and escalation in this document for the specif ### Project Spaces -For reporting issues in spaces related to a member project please use the email provided by the project for reporting. Projects handle CoC issues related to the spaces that they maintain. Projects maintainers commit to: +For reporting issues in spaces related to a member project please use the email provided by the project for reporting. +Projects handle CoC issues related to the spaces that they maintain. +Projects maintainers commit to: - maintain the confidentiality with regard to the reporter of an incident - to participate in the path for escalation as outlined in @@ -80,7 +86,8 @@ For reporting issues in spaces related to a member project please use the email ### Foundation Spaces -For reporting issues in spaces managed by the OpenJS Foundation, for example, repositories within the OpenJS organization, use the email `report@lists.openjsf.org`. The Cross Project Council (CPC) is responsible for managing these reports and commits to: +For reporting issues in spaces managed by the OpenJS Foundation, for example, repositories within the OpenJS organization, use the email `report@lists.openjsf.org`. +The Cross Project Council (CPC) is responsible for managing these reports and commits to: - maintain the confidentiality with regard to the reporter of an incident - to participate in the path for escalation as outlined in @@ -88,7 +95,9 @@ For reporting issues in spaces managed by the OpenJS Foundation, for example, re ## Escalation -The OpenJS Foundation maintains a Code of Conduct Panel (CoCP). This is a foundation-wide team established to manage escalation when a reporter believes that a report to a member project or the CPC has not been properly handled. In order to escalate to the CoCP send an email to `"coc-escalation@lists.openjsf.org`. +The OpenJS Foundation maintains a Code of Conduct Panel (CoCP). +This is a foundation-wide team established to manage escalation when a reporter believes that a report to a member project or the CPC has not been properly handled. +In order to escalate to the CoCP send an email to `"coc-escalation@lists.openjsf.org`. For more information, refer to the full [Code of Conduct governance document](https://github.com/openjs-foundation/cross-project-council/blob/master/FOUNDATION_CODE_OF_CONDUCT_REQUIREMENTS.md). diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index ced4935a1f..37db967da1 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -2,96 +2,139 @@ > Please read these guidelines before submitting an issue, filing a feature request, or contributing code. -## :question: Got a Question? +## ❓ Got a Question? 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). -## :bug: I Found a Bug +## ✏️ Filing Issues -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. +Before adding anything to the issue tracker, **please [search issues](https://github.com/mochajs/mocha/issues) to see if it's already been reported**. +Make sure to check closed and/or older issues as well. -Please include _as much detail as possible_ to help us reproduce and diagnose the bug. Most importantly: +With the exception of minor documentation typos, all changes to Mocha should be discussed in the issue tracker first. +This includes bugs, feature requests, and improvements to documentation. -- 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) +### 🐛 I Found a Bug -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. +Sorry! +It happens to the best of us. -## :exclamation: Propose a Change +Please [file an issue using the bug report template](https://github.com/mochajs/mocha/issues/new?assignees=&labels=unconfirmed-bug&projects=&template=bug_report.md) with _as much detail as possible_ to help us reproduce and diagnose the bug. +Most importantly: -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. +- 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). -_This paragraph would contain information about Mocha's roadmap, but it doesn't yet exist._ :poop: +If we need more information from you, we'll let you know. +If you don't within a few weeks, your issue will be closed for inactivity. -It's also important to understand some overarching goals of Mocha, detailed below. +### ❗️ Propose a Change -### :soccer: About Project Goals +Please [file an issue using the feature request template](https://github.com/mochajs/mocha/issues/new?assignees=&labels=feature&projects=&template=feature_request.md&title=). +Most importantly: -Mocha is a test framework. Developers use it against anything from legacy spaghetti in IE11 to stage-0 TC39 features in Electron. Mocha is committed to providing support for maintained (LTS) versions of Node.js and popular browsers (of which IE11 is still one, as of December 2018). +- Let us know _what_ the proposed change is, in as much detail as you can +- Explain _why_ you want the change +- Include your test code or file(s). + If large, please provide a link to a repository or [gist](https://gist.github.com). -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. +We'll discuss your proposed changes and how they relate to the overarching goals of Mocha, detailed below in [⚽️ About Project Goals](#⚽️-about-project-goals). -Mocha's usage far outweighs its resources. If a proposed feature would incur a maintenance penalty, it could be a hard sell. +## ⚽️ About Project Goals + +Mocha is a test framework. +Developers use it against anything from legacy spaghetti in barely-supported browsers to stage-0 TC39 features in Electron. +Mocha is committed to providing support for maintained (LTS) versions of Node.js and popular browsers. + +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. + +Mocha's usage far outweighs its resources. +If a proposed feature would incur a maintenance penalty, it could be a hard sell. We ask you please keep these goals in mind when making or proposing changes. -### :shoe: Contributing Code: Step-by-Step +## 😇 I Just Want To Help + +_Excellent._ Here's how: + +- **Handy with JavaScript?** Please check out the issues labeled [`help wanted`](https://github.com/mochajs/mocha/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) or [`good-first-issue`](https://github.com/mochajs/mocha/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Agood-first-issue). + Try `npx good-first-issue mocha`! +- **Can you write ~~good~~ well?** The [documentation](https://mochajs.org) almost always needs some love. + See the [doc-related issues](https://github.com/mochajs/mocha/issues?q=is%3Aopen+is%3Aissue+label%3Adocumentation). +- **Design your thing?** [Our site](https://mochajs.org) needs your magic touch. +- **Familiar with Mocha's codebase?** We could use your help triaging issues and/or reviewing pull requests. + Please contact an [org member](https://github.com/orgs/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/orgs/mochajs/people). +- **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 the [main chat room](https://gitter.im/mochajs/mocha)? + +## 👞 Contributing Code: Step-by-Step -Follow these steps to get going. If you are having trouble, don't be afraid to [ask for help](#got-a-question). +First follow the steps in [DEVELOPMENT.md](./DEVELOPMENT.md) to get Mocha's repository installed locally. +Then: -> PRO TIP: After `npm install`, run `npm start` to see a list of commands which can be run with `npm start ` (powered by [nps](https://npm.im/nps)). +### 🎋 Initial Creation -1. [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/creationix/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. -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. - - Do not use `yarn 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`. +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. Make your changes and add them via `git add`. - Your changes will likely be somewhere in `lib/`, `bin/` or `browser-entry.js` (if your changes are browser-specific). - - Unit and/or integration **tests are required** for any code change. These live in `test/`. + - 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. + - Keep your PR focused. + Don't fix two things at once; don't upgrade dependencies unless necessary. 1. Before committing, run `npm start 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. - - A coverage check will be sent to [Coveralls](https://coveralls.io/github/mochajs/mocha). **A drop in code coverage % is considered a failed check**. + - 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. + - A coverage check will be sent to [Coveralls](https://coveralls.io/github/mochajs/mocha). + **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. + - 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. (Optional) Ensure you are up-to-date with Mocha's `master` 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 `master` branch using `git checkout master`. - Pull changes from `upstream` using `git pull upstream master`. - If any changes were pulled in, rebase your branch onto `master` by switching back to your branch (`git checkout `) then rebasing using `git rebase master`. 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. -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. - - 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. **Do not `git merge`**. - - (Optional) [Squash](https://help.github.com/articles/about-pull-request-merges/#squash-and-merge-your-pull-request-commits) your changesets. If you have multiple changesets in your PR, they will be squashed upon PR acceptance by the Mocha team. -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 `master`. 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. 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. -Join us in the [contributors' chat](https://gitter.im/mochajs/contributors)! +At that point, hooray! 🎉 +You should see a pull request on github.com/mochajs/mocha/pulls. -## :angel: I Just Want To Help +### 🏭 PR Process -_Excellent._ Here's how: +Now that the pull request exists, some tasks will be run on it: -- **Handy with JavaScript?** Please check out the issues labeled [`help wanted`](https://github.com/mochajs/mocha/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) or [`good-first-issue`](https://github.com/mochajs/mocha/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Agood-first-issue). Try `npx good-first-issue mocha`! -- **Can you write ~~good~~ well?** The [documentation](https://mochajs.org) almost always needs some love. See the [doc-related issues](https://github.com/mochajs/mocha/issues?q=is%3Aopen+is%3Aissue+label%3Adocumentation). -- **Design your thing?** [Our site](https://mochajs.org) needs your magic touch. -- **Familiar with Mocha's codebase?** We could use your help triaging issues and/or reviewing pull requests. Please contact an [org member](https://github.com/orgs/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/orgs/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/orgs/mochajs/people)! -- **Wait--you write unit tests for _fun_?** A PR which increases coverage is unlikely to be turned down. -- **Are you experienced?** :guitar: If you're a seasoned Mocha user, why not help answer some questions in the [main chat room](https://gitter.im/mochajs/mocha)? +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. + - 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. + **Do not `git merge`**. + - (Optional) [Squash](https://help.github.com/articles/about-pull-request-merges/#squash-and-merge-your-pull-request-commits) your changesets. + If you have multiple changesets in your PR, they will be squashed upon PR acceptance by the Mocha team. +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 `master`. + 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. + +Join us in the [contributors' chat](https://gitter.im/mochajs/contributors)! diff --git a/.github/DEVELOPMENT.md b/.github/DEVELOPMENT.md new file mode 100644 index 0000000000..5e4bf73496 --- /dev/null +++ b/.github/DEVELOPMENT.md @@ -0,0 +1,20 @@ +# Development + +Follow these steps to get going in local development. +If you are having trouble, don't be afraid to [ask for help](./CONTRIBUTING.md#❓-got-a-question). + +## 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. + +## 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`. + +> PRO TIP: After `npm install`, run `npm start` to see a list of commands which can be run with `npm start ` (powered by [nps](https://npm.im/nps)). diff --git a/.github/ISSUE_TEMPLATE/01-bug.yml b/.github/ISSUE_TEMPLATE/01-bug.yml new file mode 100644 index 0000000000..2202b31280 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/01-bug.yml @@ -0,0 +1,45 @@ +body: + - attributes: + description: If any of these required steps are not taken, we may not be able to review your issue. Help us to help you! + label: Bug Report Checklist + options: + - label: I have read and agree to Mocha's [Code of Conduct](https://github.com/mochajs/mocha/blob/master/.github/CODE_OF_CONDUCT.md) and [Contributing Guidelines](https://github.com/mochajs/mocha/blob/master/.github/CONTRIBUTING.md) + required: true + - label: I have searched for [related issues](https://github.com/mochajs/mocha/issues?q=is%3Aissue) and [issues with the `faq` label](https://github.com/mochajs/mocha/issues?utf8=%E2%9C%93&q=is%3Aissue%20label%3Afaq%20), but none matched my issue. + required: true + - label: I have 'smoke tested' the code to be tested by running it outside the real test suite to get a better sense of whether the problem is in the code under test, my usage of Mocha, or Mocha itself. + required: true + type: checkboxes + - attributes: + description: What did you expect to happen? + label: Expected + type: textarea + validations: + required: true + - attributes: + description: What happened instead? + label: Actual + type: textarea + validations: + required: true + - attributes: + description: Detail the steps necessary to reproduce the problem. To get the fastest support, create an [MCVE](https://stackoverflow.com/help/mcve) and upload it to GitHub. + label: Minimal, Reproducible Example + type: textarea + validations: + required: true + - attributes: + description: What do `mocha --version`, `node_modules/.bin/mocha --version`, and `node --version` output? What name and version of browser/environment, shell, and any other related modules such as transpilers are you using?. + label: Versions + type: textarea + validations: + required: true + - attributes: + description: Any additional info you'd like to provide. + label: Additional Info + type: textarea +description: Report a bug trying to run the code +labels: + - "type: bug" +name: 🐛 Bug +title: "🐛 Bug: " diff --git a/.github/ISSUE_TEMPLATE/02-documentation.yml b/.github/ISSUE_TEMPLATE/02-documentation.yml new file mode 100644 index 0000000000..75f790fad5 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/02-documentation.yml @@ -0,0 +1,25 @@ +body: + - attributes: + description: If any of these required steps are not taken, we may not be able to review your issue. Help us to help you! + label: Documentation Request Checklist + options: + - label: I have read and agree to Mocha's [Code of Conduct](https://github.com/mochajs/mocha/blob/master/.github/CODE_OF_CONDUCT.md) and [Contributing Guidelines](https://github.com/mochajs/mocha/blob/master/.github/CONTRIBUTING.md) + required: true + - label: I have searched for [related issues](https://github.com/mochajs/mocha/issues?q=is%3Aissue) and [issues with the `faq` label](https://github.com/mochajs/mocha/issues?utf8=%E2%9C%93&q=is%3Aissue%20label%3Afaq%20), but none matched my issue. + required: true + type: checkboxes + - attributes: + description: What would you like to report? + label: Overview + type: textarea + validations: + required: true + - attributes: + description: Any additional info you'd like to provide. + label: Additional Info + type: textarea +description: Report a typo or missing area of documentation +labels: + - "area: documentation" +name: 📝 Documentation +title: "📝 Documentation: " diff --git a/.github/ISSUE_TEMPLATE/03-feature-request.yml b/.github/ISSUE_TEMPLATE/03-feature-request.yml new file mode 100644 index 0000000000..2ecb652434 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/03-feature-request.yml @@ -0,0 +1,37 @@ +body: + - attributes: + description: If any of these required steps are not taken, we may not be able to review your issue. Help us to help you! + label: Feature Request Checklist + options: + - label: I have read and agree to Mocha's [Code of Conduct](https://github.com/mochajs/mocha/blob/master/.github/CODE_OF_CONDUCT.md) and [Contributing Guidelines](https://github.com/mochajs/mocha/blob/master/.github/CONTRIBUTING.md) + required: true + - label: I have searched for [related issues](https://github.com/mochajs/mocha/issues?q=is%3Aissue) and [issues with the `faq` label](https://github.com/mochajs/mocha/issues?utf8=%E2%9C%93&q=is%3Aissue%20label%3Afaq%20), but none matched my issue. + required: true + type: checkboxes + - attributes: + description: What is the feature gap or problem you'd like to address? + label: Overview + type: textarea + validations: + required: true + - attributes: + description: How would you like to solve this need? + label: Suggested Solution + type: textarea + validations: + required: true + - attributes: + description: What other features or solutions have you also considered? + label: Alternatives + type: textarea + validations: + required: true + - attributes: + description: Any additional info you'd like to provide. + label: Additional Info + type: textarea +description: Request that a new feature be added or an existing feature improved +labels: + - "type: feature" +name: 🚀 Feature +title: "🚀 Feature: " diff --git a/.github/ISSUE_TEMPLATE/04-repository-tooling.yml b/.github/ISSUE_TEMPLATE/04-repository-tooling.yml new file mode 100644 index 0000000000..f79fe7ce50 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/04-repository-tooling.yml @@ -0,0 +1,29 @@ +body: + - attributes: + description: If any of these required steps are not taken, we may not be able to review your issue. Help us to help you! + label: Tooling Suggestion Checklist + options: + - label: I have tried restarting my IDE and the issue persists. + required: true + - label: I have pulled the latest `master` branch of the repository. + required: true + - label: I have read and agree to Mocha's [Code of Conduct](https://github.com/mochajs/mocha/blob/master/.github/CODE_OF_CONDUCT.md) and [Contributing Guidelines](https://github.com/mochajs/mocha/blob/master/.github/CONTRIBUTING.md) + required: true + - label: I have searched for [related issues](https://github.com/mochajs/mocha/issues?q=is%3Aissue) and [issues with the `faq` label](https://github.com/mochajs/mocha/issues?utf8=%E2%9C%93&q=is%3Aissue%20label%3Afaq%20), but none matched my issue. + required: true + type: checkboxes + - attributes: + description: What did you expect to be able to do? + label: Overview + type: textarea + validations: + required: true + - attributes: + description: Any additional info you'd like to provide. + label: Additional Info + type: textarea +description: Report a bug or request an enhancement in the Mocha repository's internal tooling +labels: + - "area: repository-tooling" +name: 🛠 Repository Tooling +title: "🛠 Repository Tooling: " diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index 046f15e854..0000000000 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -name: Bug report -about: To report a part of mocha not working as expected -title: '' -labels: 'unconfirmed-bug' ---- - - - -### Prerequisites - - - -- [ ] Checked that your issue hasn't already been filed by cross-referencing [issues with the `faq` label](https://github.com/mochajs/mocha/issues?utf8=%E2%9C%93&q=is%3Aissue%20label%3Afaq%20) -- [ ] Checked next-gen ES issues and syntax problems by using the same environment and/or transpiler configuration without Mocha to ensure it isn't just a feature that actually isn't supported in the environment in question or a bug in your code. -- [ ] 'Smoke tested' the code to be tested by running it outside the real test suite to get a better sense of whether the problem is in the code under test, your usage of Mocha, or Mocha itself -- [ ] Ensured that there is no discrepancy between the locally and globally installed versions of Mocha. You can find them with: `node_modules/.bin/mocha --version`(Local) and `mocha --version`(Global). We recommend that you _not_ install Mocha globally. - -### Description - - - -### Steps to Reproduce - - - -**Expected behavior:** [What you expect to happen] - -**Actual behavior:** [What actually happens] - - -**Reproduces how often:** [What percentage of the time does it reproduce?] - -### Versions - - - -- The output of `mocha --version` and `node_modules/.bin/mocha --version`: -- The output of `node --version`: -- Your operating system - - name and version: - - architecture (32 or 64-bit): -- Your shell (e.g., bash, zsh, PowerShell, cmd): -- Your browser and version (if running browser tests): -- Any third-party Mocha-related modules (and their versions): -- Any code transpiler (e.g., TypeScript, CoffeeScript, Babel) being used (and its version): - -### Additional Information - - diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000000..d07b80847e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,14 @@ +blank_issues_enabled: false +contact_links: + - name: Documentation Website + about: Please read our documentation website before filing new issues. + url: https://mochajs.org + - name: Documentation Website > APIs + about: If you're using Mocha's API, see also the website's API docs. + url: https://mochajs.org/api + - name: Gitter Chat + about: Our chat room is the right place for quick informal questions. + url: http://gitter.im/mochajs/mocha + - name: StackOverflow + about: For more questions, see the `mocha` tag on StackOverflow. + url: https://stackoverflow.com/questions/tagged/mocha diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md deleted file mode 100644 index 8a8343e96f..0000000000 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -name: Feature request -about: Suggest an idea for Mocha -title: '' -labels: 'feature' ---- - -**Is your feature request related to a problem or a nice-to-have?? Please describe.** -A clear and concise description of what the problem is. E.g. I'm always frustrated when [...] - -**Describe the solution you'd like** -A clear and concise description of what you want to happen. - -**Describe alternatives you've considered** -A clear and concise description of any alternative solutions or features you've considered. - -**Additional context** -Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/support-question.md b/.github/ISSUE_TEMPLATE/support-question.md deleted file mode 100644 index 93f367cee5..0000000000 --- a/.github/ISSUE_TEMPLATE/support-question.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -name: Support Question -about: If you have a question, please check out our Gitter or StackOverflow! -title: '' -labels: 'question' ---- - - diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 37271e9cb0..9f8ff8ca6a 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,40 +1,13 @@ -### Requirements + -* Filling out the template is required. Any pull request that does not include enough information to be reviewed in a timely manner may be closed at the maintainers' discretion. -* All new code requires tests to ensure against regressions. +## PR Checklist -### Description of the Change +- [ ] Addresses an existing open issue: fixes #000 +- [ ] That issue was marked as [`status: accepting prs`](https://github.com/mochajs/mocha/issues?q=is%3Aopen+is%3Aissue+label%3A%22status%3A+accepting+prs%22) +- [ ] Steps in [CONTRIBUTING.md](https://github.com/mochajs/mocha/blob/main/.github/CONTRIBUTING.md) were taken - - -### Alternate Designs - - - -### Why should this be in core? - - - -### Benefits - - - -### Possible Drawbacks - - - -### Applicable issues - - + diff --git a/MAINTAINERS.md b/MAINTAINERS.md index a029bc536f..2db1587329 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -1,42 +1,5 @@ # Mocha Maintainer's Handbook - - -- [Introduction](#introduction) -- [Terminology](#terminology) - - [User](#user) - - [Contributor](#contributor) - - [A Note About Donations](#a-note-about-donations) - - [Maintainer](#maintainer) - - [The Responsibilities of a Maintainer](#the-responsibilities-of-a-maintainer) - - [The Rights of a Maintainer](#the-rights-of-a-maintainer) - - [About "Owners"](#about-owners) -- [Mocha's Decision-Making Process](#mochas-decision-making-process) -- [Communication](#communication) -- [Working with Issues & Pull Requests](#working-with-issues--pull-requests) - - [Semantic Versioning](#semantic-versioning) - - [Questions](#questions) - - [Bugs](#bugs) - - [Features](#features) - - [Subsystems, Environments, Etc.](#subsystems-environments-etc) - - [Feedback & Follow-ups](#feedback--follow-ups) - - [Meta](#meta) - - [Closing Issues](#closing-issues) -- [Commenting on Issues and Reviewing Pull Requests](#commenting-on-issues-and-reviewing-pull-requests) - - [Reviewing Code](#reviewing-code) - - [The Part About Jerks](#the-part-about-jerks) - - [Rude or Entitled People](#rude-or-entitled-people) - - [Code of Conduct Violations](#code-of-conduct-violations) -- [Branches](#branches) -- [Merging PRs](#merging-prs) - - [Using Milestones](#using-milestones) -- [Mocha's Release Process](#mochas-release-process) -- [Projects](#projects) -- [About The JS Foundation](#about-the-js-foundation) -- [About OpenCollective](#about-opencollective) - - - ## Introduction Hi stranger! We've written this document for: @@ -45,7 +8,10 @@ Hi stranger! We've written this document for: 1. Prospective maintainers of Mocha 1. Anyone curious about how Mocha's maintainers maintain Mocha -The purpose of this document is to _describe our processes_. We want to avoid conflicts and confusion around "unwritten rules". In our opinion, the most straightforward way to address this is to _write them down_. This _also_ happens to be the most straightforward way to change them! +The purpose of this document is to _describe our processes_. +We want to avoid conflicts and confusion around "unwritten rules". +In our opinion, the most straightforward way to address this is to _write them down_. +This _also_ happens to be the most straightforward way to change them! To assist in eliminating ambiguity, we will define some terms. @@ -55,13 +21,15 @@ Anyone involved with Mocha will fall into one of these buckets: **user**, **cont ### User -A "user" for the purpose of this document is any _individual developer_ who consumes Mocha to write and/or execute tests. A user interacts with contributors. A user interacts with the software, web site, documentation, etc., which these contributors provide. +A "user" for the purpose of this document is any _individual developer_ who consumes Mocha to write and/or execute tests. +A user interacts with contributors. +A user interacts with the software, web site, documentation, etc., which these contributors provide. -As a user, you're expected to follow the [code of conduct](https://github.com/mochajs/mocha/blob/master/.github/CODE_OF_CONDUCT.md) when interacting in Mocha's "official" social spaces. This includes: +As a user, you're expected to follow the [code of conduct](https://github.com/mochajs/mocha/blob/master/.github/CODE_OF_CONDUCT.md) when interacting in Mocha's "official" social spaces. +This includes: - Any chatroom under the `mochajs` organization on Gitter - Any project under the `mochajs` organization on GitHub -- The MochaJS Google Group - Any future social, in-person or online events which Mocha might organize ### Contributor @@ -70,7 +38,8 @@ This is the most important thing: **You don't have to write code to be a contributor!** -A "contributor" is any individual who has _given back_ in some way to the project and its community. Contributions include (but are not limited to): +A "contributor" is any individual who has _given back_ in some way to the project and its community. +Contributions include (but are not limited to): 1. Reporting bugs which follow the reporting guidelines 1. Suggesting and debating enhancements that have wide applicability @@ -84,11 +53,13 @@ A "contributor" is any individual who has _given back_ in some way to the projec 1. Recruiting more contributors! Don't spam. 1. Researching the user base, getting feedback, etc. Don't spam. -A contributor is _usually_ a user as well, but this isn't a hard-and-fast rule. A contributor is also expected to adhere to the [code of conduct](https://github.com/mochajs/mocha/blob/master/.github/CODE_OF_CONDUCT.md) as a user would. +A contributor is _usually_ a user as well, but this isn't a hard-and-fast rule. +A contributor is also expected to adhere to the [code of conduct](https://github.com/mochajs/mocha/blob/master/.github/CODE_OF_CONDUCT.md) as a user would. As you can see, it's wide open! Think of it another way: if you are _adding value to Mocha_, then you are a contributor. -> Due to the nature of GitHub, it's a challenge to recognize those who've made contributions _elsewhere_ on the web, or even contributions of the "non-code" variety. If you know of any great contributions which have gone unnoticed, please bring them to the maintainers' attention! +> Due to the nature of GitHub, it's a challenge to recognize those who've made contributions _elsewhere_ on the web, or even contributions of the "non-code" variety. +If you know of any great contributions which have gone unnoticed, please bring them to the maintainers' attention! #### A Note About Donations @@ -98,11 +69,14 @@ We love our backers and sponsors! 💕 ### Maintainer -A maintainer has certain "rights" (or "permissions") to the Mocha project and other projects under the `mochajs` organization. There's no way to dance around this: with these rights come increased responsibilities. +A maintainer has certain "rights" (or "permissions") to the Mocha project and other projects under the `mochajs` organization. +There's no way to dance around this: with these rights come increased responsibilities. -However, **there is no expectation of a standard of technical ability** to be a maintainer of Mocha. This doesn't imply a lack of technical oversight--every pull request will eventually be reviewed. +However, **there is no expectation of a standard of technical ability** to be a maintainer of Mocha. +This doesn't imply a lack of technical oversight--every pull request will eventually be reviewed. -**If you think you aren't experienced enough to maintain a project like Mocha, you are incorrect.** The only requirements are the above responsibilities and a desire to help the project. It bears repeating: +**If you think you aren't experienced enough to maintain a project like Mocha, you are incorrect.** The only requirements are the above responsibilities and a desire to help the project. +It bears repeating: **You don't have to write code to be a maintainer!** @@ -110,14 +84,19 @@ However, **there is no expectation of a standard of technical ability** to be a #### The Responsibilities of a Maintainer -As a maintainer, you are expected to _not just_ "follow" the code of conduct, but embody its values. Your public behavior, whether in the physical or virtual world, reflects upon the project and other maintainers. +As a maintainer, you are expected to _not just_ "follow" the code of conduct, but embody its values. +Your public behavior, whether in the physical or virtual world, reflects upon the project and other maintainers. > If you don't understand the code of conduct, or why it exists, it is _your responsibility_ to educate yourself. > This does not imply the CoC is immutable. -Furthermore, a maintainer is a contributor who **contributes regularly**, or expresses a _desire to do so._ That could be every day--but it might be once a week, or even once a month. Your boss doesn't work here; contribute as often as you wish. We are all people with Real Lives, and for many of us, contributing to OSS is just a hobby! +Furthermore, a maintainer is a contributor who **contributes regularly**, or expresses a _desire to do so._ That could be every day--but it might be once a week, or even once a month. +Your boss doesn't work here; contribute as often as you wish. +We are all people with Real Lives, and for many of us, contributing to OSS is just a hobby! -Finally, a maintainer must help define what makes Mocha "Mocha". At minimum, a maintainer must _understand_ the current definition (if a maintainer is not interested in decision-making). Some of these questions include: +Finally, a maintainer must help define what makes Mocha "Mocha". +At minimum, a maintainer must _understand_ the current definition (if a maintainer is not interested in decision-making). +Some of these questions include: - What's the scope of Mocha? - Where should we focus efforts? @@ -144,7 +123,9 @@ You may choose to do zero or more of these _at their discretion_: - Add new maintainers to the team - Tag releases and publish Mocha to npm -> While maintainers have the ability to commit directly to the `master` branch, _this is to be avoided_ if any other maintainer could reasonably take issue with the change, or the change affects Mocha's API or output. For example, a spelling correction in `CHANGELOG.md` may not require a pull request. A change to a reporter's output most certainly would! Maintainers are trusted to use their best judgement; if unsure, err on the side of caution. +> While maintainers have the ability to commit directly to the `master` branch, _this is to be avoided_ if any other maintainer could reasonably take issue with the change, or the change affects Mocha's API or output. +For example, a spelling correction in `CHANGELOG.md` may not require a pull request. +A change to a reporter's output most certainly would! Maintainers are trusted to use their best judgement; if unsure, err on the side of caution. #### About "Owners" @@ -155,20 +136,27 @@ Some maintainers will have full admin rights to the [mochajs org](https://github ## Mocha's Decision-Making Process -Mocha follows a [consensus-seeking decision-making](https://en.wikipedia.org/wiki/Consensus-seeking_decision-making) process. In other words, all maintainers attempt to come to agreement. If that fails, we decide by a simple vote. +Mocha follows a [consensus-seeking decision-making](https://en.wikipedia.org/wiki/Consensus-seeking_decision-making) process. +In other words, all maintainers attempt to come to agreement. +If that fails, we decide by a simple vote. -Active maintainers will make an effort to solicit feedback from others before making important or potentially controversial decisions. Given the varying geographical distribution and availability of the maintenance team, we resolve to do the best we can to solicit feedback. +Active maintainers will make an effort to solicit feedback from others before making important or potentially controversial decisions. +Given the varying geographical distribution and availability of the maintenance team, we resolve to do the best we can to solicit feedback. -In other words, to have your opinion heard, participate regularly. The rest of the team won't wait on feedback that isn't necessarily forthcoming! +In other words, to have your opinion heard, participate regularly. +The rest of the team won't wait on feedback that isn't necessarily forthcoming! ## Communication -Maintainers will mainly gather in [the mochajs/contributors channel](https://gitter.im/mochajs/contributors). This is a _public_ channel, and _anyone_ can join. -Videoconference (or audio) calls may happen on a regular or irregular basis, as schedules allow. This is mainly because we have Real Lives and time zones suck. +Maintainers will mainly gather in [the mochajs/contributors channel](https://gitter.im/mochajs/contributors). +This is a _public_ channel, and _anyone_ can join. +Videoconference (or audio) calls may happen on a regular or irregular basis, as schedules allow. +This is mainly because we have Real Lives and time zones suck. ## Working with Issues & Pull Requests -All new issues will need to be triaged, and pull requests must be examined. Maintainers must understand [Semantic Versioning](http://semver.org) ("SemVer"), as Mocha follows it strictly. +All new issues will need to be triaged, and pull requests must be examined. +Maintainers must understand [Semantic Versioning](http://semver.org) ("SemVer"), as Mocha follows it strictly. > If you see an issue or PR that could use some labels, please add them! @@ -211,54 +199,94 @@ Examples of a breaking changes might be: - The exception is fixing likely false-positives - A good example would be changing the default `timeout` value -### Questions +## Issue Triage + +Issues should be filed according to one of our [GitHub Issue forms](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms). +If any required information is missing, add the `status: waiting for author` label and politely ask for the missing information. + +### Issue Meta + +For all issues, apply the following labels based on which area(s) the issue pertains to: + +- `area: async`: Issues around Mocha's asynchronous usage +- `area: browser`: Issues unique to a browser environment +- `area: parallel`: Issues around Mocha's parallel mode +- `area: qa`: Issues around Mocha's own test suite +- `area: reporter`: Usually concerning Mocha's output +- `area: security`: Involving vulnerabilities, actual or potential +- `area: windows`: Windows-specific issues, particularly around path discrepancies + +Additionally: + +- `good first issue`: If the implementation is likely doable by someone who's never contributed to Mocha (or potentially any other open source project) before +- `status: duplicate`: If an equivalent issue was already filed, add this label, close as not planned, and comment with something like `duplicate of #` +- `status: in discussion`: Add this whenever the issue is blocked on community input and/or deeper discussions +- `status: waiting for author`: Add this whenever the issue is blocked on something from the author + +### 🐛 Bugs + +Bug reports should include a way to reproduce the issue that someone who is not deeply familiar with Mocha can work with locally. -Support questions should be answered if possible, but the user should be directed to the chat room, StackOverflow, or Google Groups for further help, _if_ it is indeed a Mocha-related issue. +Depending on that reproduction, add the following label(s) in addition to the auto-added `type: bug`: -If it's _not_ a Mocha problem (people tend not to believe this), you may want to show a counter-example. It's often helpful to direct the issue author to the responsible project, if you can determine what that is. +- If the bug is valid and reproduction works: add `status: accepting prs` +- If the bug might be valid but the reproduction isn't workable: + - Add `status: waiting for author` + - Politely comment explaining why the reproduction isn't workable +- If the bug might be valid but it's not clear whether it's worth it: + - Add `status: in discussion` + - Explain that it _might_ be worth it and that more community input is needed +- If the bug is clearly not worth it or valid, explain why, close the issue as not planned, and: + - If it isn't a bug at all: add the `invalid` label + - If it is roughly a bug but isn't something that can or should be fixed: add the `status: wontfix` label -- `faq`: Issues which are _repeatedly_ asked support questions or misunderstandings. This may also apply to questions which receive a lot of 👍's -- `question`: Add this label if it's just a support question +### 📝 Documentation -### Bugs +Documentation reports should clearly indicate a gap or problem that should be addressed in documentation. +Triage documentation issues similar to bugs and/or feature requests - documentation is its own form of product area. +Keep the auto-added `area: documentation` label. -- `confirmed-bug`: A confirmed bug -- `unconfirmed-bug`: A maintainer has not yet or cannot reproduce; typically `needs-feedback` follows (see "Feedback & Follow-ups" below) -- `invalid`: Not a bug. Close the issue. -- `wontfix`: A bug, but for Reasons, it won't get fixed. +### 🚀 Features -### Features +Feature requests should include a compelling reason why we should spend the maintenance time on the feature. +Given that Mocha is prioritizing stability over growth, this can be a high bar. -- `feature`: Any feature/enhancement that's up for discussion or has been agreed upon. -- `wontfix`: A half-baked feature or one which is unsuitable or out-of-scope for Mocha. +Depending on the reasoning, add the following label(s) in addition to the auto-added `type: feature`: -### Subsystems, Environments, Etc. +- If the reasoning is valid and seems worth the maintenance cost: add `status: accepting prs` +- If the reasoning is unclear: + - Add `status: waiting for author` + - Politely comment explaining what's missing +- If the feature might be valid but it's not clear whether it's worth it: + - Add `status: in discussion` + - Explain that it _might_ be worth it and that more community input is needed +- If the feature is not valid, explain why, close the issue as not planned, and: + - If it isn't a feature request at all: add the `invalid` label + - If it is roughly a feature request but isn't something that can or should be implemented: add the `status: wontfix` label -- `reporter`: Usually concerning Mocha's output -- `browser`: Issues unique to a browser environment -- `documentation`: Issues around incorrect or missing docs -- `qa`: Issues around Mocha's own test suite -- `chore`: Refactors, CI tweaks, dependencies, etc. -- `developer-experience`: Issues which will make it easier to contribute and maintain Mocha +### 🛠 Tooling -### Feedback & Follow-ups +Issues filed about improvements to Mocha's internal development processes. +These can be more informally discussed by maintainers. +Keep the auto-added `area: repository tooling`. -Issues or PRs which require action or feedback from a _specific_ maintainer, should have that item _assigned_ to them. +### ❓ Questions -- `needs-feedback`: Issues which _need feedback from the original author_. Will automatically become `stale` (see "Meta" section below) -- `needs-review`: For _pull requests only_; PRs which need a maintainer to inspect and/or merge them +Our issue tracker is not the right place to ask questions. +If an issue is filed that seems like it's more of a question, add the `type: question` label, politely direct the user to the [❓ Got a Question?](./.github/CONTRIBUTING.md#❓-got-a-question) section, and close the issue as not planned. -### Meta +If it's _not_ a Mocha problem (people tend not to believe this), you may want to show a counter-example. +It's often helpful to direct the issue author to the responsible project, if you can determine what that is. -- `stale`: The "stalebot" marks things as stale and will close issues if they need feedback but haven't received any. Comment on an issue to prevent this from happening. -- `help wanted`: If it's an issue that is not a high priority for the maintenance team, use this label to solicit contributions. Note lack of `-` in this label's name. -- `good-first-issue`: Typically combined with `help wanted`; an issue that new contributors to Mocha may find straightforward. +If this issue seems to be _repeatedly_ asked, add the `faq` label. +This may also apply to questions which receive a lot of 👍 reactions. ### Closing Issues Write "closes #" or "resolves #" in a commit or PR to have the original issue closed automatically once the PR is merged. -For any issue which is a duplicate, write "duplicate of #" in a new comment, and close the issue. [Read more about marking issues as duplicates](https://help.github.com/articles/about-duplicate-issues-and-pull-requests/). +For any issue which is a duplicate, write "duplicate of #" in a new comment, and close the issue. +[Read more about marking issues as duplicates](https://help.github.com/articles/about-duplicate-issues-and-pull-requests/). If the issue is a support question, and you believe it has been answered, close the issue. @@ -266,13 +294,18 @@ If the issue is not Mocha-related, and/or a bug cannot be confirmed, label it `i ## Commenting on Issues and Reviewing Pull Requests -**All maintainers should be courteous and kind.** Thank the external contributor for the pull request, even if it is not merged. If the pull request has been opened (and subsequently closed) without discussion in a corresponding issue, let them know that by creating an issue first, they could have saved wasted effort. _Clearly and objectively_ explain the reasoning for rejecting any PR. +**All maintainers should be courteous and kind.** Thank the external contributor for the pull request, even if it is not merged. +If the pull request has been opened (and subsequently closed) without discussion in a corresponding issue, let them know that by creating an issue first, they could have saved wasted effort. +_Clearly and objectively_ explain the reasoning for rejecting any PR. -If you need more information in an issue, nicely ask the user to provide it. Remind them to use the issue/PR templates if they have not. If the user never gets around to it, the "stalebot" will close it eventually anyhow. +If you need more information in an issue, nicely ask the user to provide it. +Remind them to use the issue/PR templates if they have not. ### Reviewing Code -Use GitHub's code review features. Requesting a review from another maintainer _may or may not_ actually result in a review; don't wait on it. If the PR cannot move forward without input from a certain maintainer, _assign them to the PR_. +Use GitHub's code review features. +Requesting a review from another maintainer _may or may not_ actually result in a review; don't wait on it. +If the PR cannot move forward without input from a certain maintainer, _assign them to the PR_. ### The Part About Jerks @@ -280,31 +313,41 @@ There will be jerks. #### Rude or Entitled People -These are users who feel the Mocha project and its maintainers _owe them_ time or support. This is incorrect. +These are users who feel the Mocha project and its maintainers _owe them_ time or support. +This is incorrect. -However, this behavior is often indicative of someone who is "new" to open source. Many just don't know better. It is not your _responsibility_ to educate them (again, you owe them nothing). +However, this behavior is often indicative of someone who is "new" to open source. +Many just don't know better. +It is not your _responsibility_ to educate them (again, you owe them nothing). Here are some suggestions: 1. If u mad, wait 20 minutes before writing a comment. -1. "Kill them with kindness". Explain how they are presenting themselves; maybe link to a good article or two about it. -1. Don't make it about "users vs. maintainers". Treat them like a potential future maintainer. -1. Avoid adding to the drama. You could try to reach out privately; email may be in their GitHub profile. You will likely never hear from that individual again (problem solved) +1. "Kill them with kindness". + Explain how they are presenting themselves; maybe link to a good article or two about it. +1. Don't make it about "users vs. + maintainers". + Treat them like a potential future maintainer. +1. Avoid adding to the drama. + You could try to reach out privately; email may be in their GitHub profile. + You will likely never hear from that individual again (problem solved) 1. If an issue is getting out of control, lock it. -1. If someone is _repeatedly_ rude and does not correct their mistakes, you may ban them from participating in the `mochajs` org. If you do not have permission to do so, contact one which does (an "owner"). +1. If someone is _repeatedly_ rude and does not correct their mistakes, you may ban them from participating in the `mochajs` org. + If you do not have permission to do so, contact one which does (an "owner"). #### Code of Conduct Violations **This section is theoretical, as it's yet to happen**. 1. Inform the individual of the violation; link to the CoC -1. Follow up with JS Foundation for further guidance +1. Follow up with OpenJS Foundation for further guidance 1. Repeated violators will be banned inasmuch as that is technically possible 1. No maintainer nor contributor is exempt from the CoC ## Branches -`master` is the only maintained branch in `mochajs/mocha` or any of the other repos. **`master` is the only branch to which force-pushing is disallowed.** +`master` is the only maintained branch in `mochajs/mocha` or any of the other repos. +**`master` is the only branch to which force-pushing is disallowed.** Maintainers may push new branches to a repo, as long as they remove them when finished (merging a PR will prompt to do so). @@ -312,7 +355,8 @@ Please _please_ **_please_** delete old or unused branches. ## Merging PRs -GitHub has several options for how to merge a PR. Here's what we do: +GitHub has several options for how to merge a PR. +Here's what we do: 1. _If a PR has multiple commits_, "Squash". 1. _If a PR has a single commit_, "Rebase". @@ -322,11 +366,13 @@ GitHub has several options for how to merge a PR. Here's what we do: ### Using Milestones -If you know that the PR is breaking, assign it to a new or existing milestone correlating with the next major release. For example, if Mocha's current version is v6.5.2, then this milestone would be named `v7.0.0`. +If you know that the PR is breaking, assign it to a new or existing milestone correlating with the next major release. +For example, if Mocha's current version is v6.5.2, then this milestone would be named `v7.0.0`. Likewise, if the PR is `semver-minor`, create or use a new milestone correlating to the next _minor_ release, e.g., `v6.6.0`. -If it's unclear what the next milestone will be, use or create a milestone named `next`. This milestone will be renamed to the new version at release time. +If it's unclear what the next milestone will be, use or create a milestone named `next`. +This milestone will be renamed to the new version at release time. By using milestones, we can cherry-pick non-breaking changes into minor or patch releases, and keep `master` as the latest version. @@ -338,30 +384,42 @@ _It's easier to release often._ 1. Decide whether this is a `patch`, `minor`, or `major` release. 1. Checkout `master` in your working copy & pull. -1. Modify `CHANGELOG.md`; follow the existing conventions in that file. Use the "pull request" number, unless there isn't one. _You do not need to add Markdown links; this is done automatically._ +1. Modify `CHANGELOG.md`; follow the existing conventions in that file. + Use the "pull request" number, unless there isn't one. + _You do not need to add Markdown links; this is done automatically._ 1. You can omit stuff from `CHANGELOG.md` that was done by a maintainer, but would have no interest to consumers of Mocha. - 1. If the changes aren't of interest to consumers but _were not_ made by a maintainer, reference them anyway. It's cool to give attribution! -1. Use `npm version` (use `npm@8+`) to bump the version; see `npm version --help` for more info. (Hint--use `-m`: e.g., `npm version patch -m 'Release v%s'`) + 1. If the changes aren't of interest to consumers but _were not_ made by a maintainer, reference them anyway. + It's cool to give attribution! +1. Use `npm version` (use `npm@8+`) to bump the version; see `npm version --help` for more info. + (Hint--use `-m`: e.g., `npm version patch -m 'Release v%s'`) 1. This command will update the list of authors (from the Git history) in `AUTHORS`, and add GitHub links to `CHANGELOG.md`. 1. These changes are then added to the Git "stage" and will be added to the commit. 1. Push `master` to `origin` with your new tag; e.g. `git push origin master --tags` -1. Copy & paste the `CHANGELOG.md` lines to a new GitHub "release". Save release as draft. +1. Copy & paste the `CHANGELOG.md` lines to a new GitHub "release". + Save release as draft. 1. Meanwhile, you can check [the build](https://travis-ci.org/mochajs/mocha) on Travis-CI and [GitHub Actions](https://github.com/mochajs/mocha/actions?query=workflow%3A%22Windows+CI%22). 1. Once the build is green, you'll want to trigger an update of `mochajs.org`: - 1. _If you're doing a prerelease_, fast-forward the `next` branch to `master`, and push it. This updates [https://next.mochajs.org](https://next.mochajs.org). That's all. - 1. _If this is NOT a prerelease_, fast-forward the `mochajs.org` branch to `master` and push it. This updates [https://mochajs.org](https://mochajs.org). + 1. _If you're doing a prerelease_, fast-forward the `next` branch to `master`, and push it. + This updates [https://next.mochajs.org](https://next.mochajs.org). + That's all. + 1. _If this is NOT a prerelease_, fast-forward the `mochajs.org` branch to `master` and push it. + This updates [https://mochajs.org](https://mochajs.org). 1. _If this is a "final" release_ (the first release of a major _after_ one or more prereleases) then remove the `next` tag from npm via `npm dist-tag rm next`. 1. Finally, you're satisfied with the release notes, open your draft release on GitHub, then click "publish." -1. Back in your working copy, run `npm publish`. _If you're doing a prerelease, ensure that you use `--tag=next`._ -1. Announce the update on Twitter or just tell your dog or something. New releases will be automatically tweeted by [@b0neskull](https://twitter.com/b0neskull) via a feed subscription to Mocha's "releases" page on GitHub. +1. Back in your working copy, run `npm publish`. + _If you're doing a prerelease, ensure that you use `--tag=next`._ +1. Announce the update on Twitter or just tell your dog or something. + New releases will be automatically tweeted by [@b0neskull](https://twitter.com/b0neskull) via a feed subscription to Mocha's "releases" page on GitHub. _Note: there are too many steps above._ -## About The JS Foundation +## About The OpenJS Foundation -The [JS Foundation](https://js.foundation) retains copyright of all projects underneath the [mochajs org](https://github.com/mochajs). The Foundation does not influence technical decisions nor the project roadmap. It is, however, charged with ensuring the continued vitality and sustainability of projects under its banner. +The [OpenJS Foundation](https://js.foundation) retains copyright of all projects underneath the [mochajs org](https://github.com/mochajs). +The Foundation does not influence technical decisions nor the project roadmap. +It is, however, charged with ensuring the continued vitality and sustainability of projects under its banner. -As a maintainer, you have access to the resources the JS Foundation provides. +As a maintainer, you have access to the resources the OpenJS Foundation provides. ## About OpenCollective diff --git a/README.md b/README.md index 0e5b677e7f..d789264160 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@

- Mocha test framework + Mocha test framework logo

☕️ Simple, flexible, fun JavaScript test framework for Node.js & The Browser ☕️

@@ -22,10 +22,11 @@ ## Links -- **[Documentation](https://mochajs.org/)** +- **[Documentation](https://mochajs.org)** - **[Release Notes / History / Changes](https://github.com/mochajs/mocha/blob/master/CHANGELOG.md)** - [Code of Conduct](https://github.com/mochajs/mocha/blob/master/.github/CODE_OF_CONDUCT.md) - [Contributing](https://github.com/mochajs/mocha/blob/master/.github/CONTRIBUTING.md) +- [Development](https://github.com/mochajs/mocha/blob/master/.github/DEVELOPMENT.md) - [Gitter Chatroom](https://gitter.im/mochajs/mocha) (ask questions here!) - [Issue Tracker](https://github.com/mochajs/mocha/issues) @@ -37,7 +38,10 @@ ## Sponsors -Does your company use Mocha? Ask your manager or marketing team if your company would be interested in supporting our project. Support will allow the maintainers to dedicate more time for maintenance and new features for everyone. Also, your company's logo will show [on GitHub](https://github.com/mochajs/mocha#readme) and on [our site](https://mochajs.org#sponsors) - who doesn't want a little extra exposure? [Here's the info](https://opencollective.com/mochajs). +Does your company use Mocha? Ask your manager or marketing team if your company would be interested in supporting our project. +Support will allow the maintainers to dedicate more time for maintenance and new features for everyone. +Also, your company's logo will show [on GitHub](https://github.com/mochajs/mocha#readme) and on [our site](https://mochajs.org#sponsors) - who doesn't want a little extra exposure? +[Here's the info](https://opencollective.com/mochajs). [![MochaJS Sponsor](https://opencollective.com/mochajs/tiers/sponsors/0/avatar)](https://opencollective.com/mochajs/tiers/sponsors/0/website) [![MochaJS Sponsor](https://opencollective.com/mochajs/tiers/sponsors/1/avatar)](https://opencollective.com/mochajs/tiers/sponsors/1/website) From bbbd0cb599dd58da8121c0e212c3cb995646173b Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Sat, 2 Dec 2023 16:17:41 -0500 Subject: [PATCH 2/7] Missed a note: re-requesting review --- .github/CONTRIBUTING.md | 39 ++++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 37db967da1..fd4e157394 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -80,25 +80,25 @@ Then: ### 🎋 Initial Creation 1. Create a new branch in your working copy. - Give your branch a descriptive name, such as `issue/12345`: `git checkout -b issue/12345`. + Give your branch a descriptive name, such as `issue/12345`: `git checkout -b issue/12345`. 1. Make your changes and add them via `git add`. - Your changes will likely be somewhere in `lib/`, `bin/` or `browser-entry.js` (if your changes are browser-specific). - Unit and/or integration **tests are required** for any code change. - These live in `test/`. + 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. + Don't fix two things at once; don't upgrade dependencies unless necessary. 1. Before committing, run `npm start 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. + The first step to ensuring these checks pass is to test on your own machine. - A coverage check will be sent to [Coveralls](https://coveralls.io/github/mochajs/mocha). - **A drop in code coverage % is considered a failed check**. + **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. + If ESLint fails to fix an issue, your commit will fail and you will need to manually correct the problem. 1. (Optional) Ensure you are up-to-date with Mocha's `master` 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 `master` branch using `git checkout master`. @@ -106,10 +106,10 @@ Then: - If any changes were pulled in, rebase your branch onto `master` by switching back to your branch (`git checkout `) then rebasing using `git rebase master`. 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. + 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. + Once you're satisfied, submit the form. At that point, hooray! 🎉 You should see a pull request on github.com/mochajs/mocha/pulls. @@ -119,22 +119,23 @@ You should see a pull request on github.com/mochajs/mocha/pulls. 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. + 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. + The result of these checks will be displayed on your PR. - If the checks fail, you must address those before the PR is accepted. - 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. - **Do not `git merge`**. + 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. + **Do not `git merge`**. - (Optional) [Squash](https://help.github.com/articles/about-pull-request-merges/#squash-and-merge-your-pull-request-commits) your changesets. - If you have multiple changesets in your PR, they will be squashed upon PR acceptance by the Mocha team. + If you have multiple changesets in your PR, they will be squashed upon PR acceptance by the Mocha team. 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. + 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 `master`. - If this is the case, you will need to [update your PR](#up-to-date) and resolve your conflicts. + 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. + 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). Join us in the [contributors' chat](https://gitter.im/mochajs/contributors)! From ea15a4b81b041d9b04668138855540b96b382949 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Tue, 5 Dec 2023 12:13:47 -0500 Subject: [PATCH 3/7] Switch from rebasing to squashing --- .github/CONTRIBUTING.md | 7 +------ MAINTAINERS.md | 46 +++++++++++++++++++---------------------- 2 files changed, 22 insertions(+), 31 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index fd4e157394..76f1b9f486 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -103,7 +103,7 @@ Then: - You can add an "upstream" remote repo using `git remote add upstream https://github.com/mochajs/mocha.git && git fetch upstream`. - Navigate to your `master` branch using `git checkout master`. - Pull changes from `upstream` using `git pull upstream master`. - - If any changes were pulled in, rebase your branch onto `master` by switching back to your branch (`git checkout `) then rebasing using `git rebase master`. + - If any changes were pulled in, update your branch from `master` by switching back to your branch (`git checkout `) then merging using `git merge master`. 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. @@ -123,11 +123,6 @@ Now that the pull request exists, some tasks will be run on it: 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. - - 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. - **Do not `git merge`**. - - (Optional) [Squash](https://help.github.com/articles/about-pull-request-merges/#squash-and-merge-your-pull-request-commits) your changesets. - If you have multiple changesets in your PR, they will be squashed upon PR acceptance by the Mocha team. 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. diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 2db1587329..98b07d5455 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -59,7 +59,7 @@ A contributor is also expected to adhere to the [code of conduct](https://github As you can see, it's wide open! Think of it another way: if you are _adding value to Mocha_, then you are a contributor. > Due to the nature of GitHub, it's a challenge to recognize those who've made contributions _elsewhere_ on the web, or even contributions of the "non-code" variety. -If you know of any great contributions which have gone unnoticed, please bring them to the maintainers' attention! +> If you know of any great contributions which have gone unnoticed, please bring them to the maintainers' attention! #### A Note About Donations @@ -124,8 +124,8 @@ You may choose to do zero or more of these _at their discretion_: - Tag releases and publish Mocha to npm > While maintainers have the ability to commit directly to the `master` branch, _this is to be avoided_ if any other maintainer could reasonably take issue with the change, or the change affects Mocha's API or output. -For example, a spelling correction in `CHANGELOG.md` may not require a pull request. -A change to a reporter's output most certainly would! Maintainers are trusted to use their best judgement; if unsure, err on the side of caution. +> For example, a spelling correction in `CHANGELOG.md` may not require a pull request. +> A change to a reporter's output most certainly would! Maintainers are trusted to use their best judgement; if unsure, err on the side of caution. #### About "Owners" @@ -324,16 +324,16 @@ Here are some suggestions: 1. If u mad, wait 20 minutes before writing a comment. 1. "Kill them with kindness". - Explain how they are presenting themselves; maybe link to a good article or two about it. + Explain how they are presenting themselves; maybe link to a good article or two about it. 1. Don't make it about "users vs. - maintainers". - Treat them like a potential future maintainer. + maintainers". + Treat them like a potential future maintainer. 1. Avoid adding to the drama. - You could try to reach out privately; email may be in their GitHub profile. - You will likely never hear from that individual again (problem solved) + You could try to reach out privately; email may be in their GitHub profile. + You will likely never hear from that individual again (problem solved) 1. If an issue is getting out of control, lock it. 1. If someone is _repeatedly_ rude and does not correct their mistakes, you may ban them from participating in the `mochajs` org. - If you do not have permission to do so, contact one which does (an "owner"). + If you do not have permission to do so, contact one which does (an "owner"). #### Code of Conduct Violations @@ -355,12 +355,8 @@ Please _please_ **_please_** delete old or unused branches. ## Merging PRs -GitHub has several options for how to merge a PR. -Here's what we do: - -1. _If a PR has multiple commits_, "Squash". -1. _If a PR has a single commit_, "Rebase". -1. Don't "Merge". +We prefer to [squash merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-commits) PRs. +Requiring users to keep clean histories for rebasing would be a large ask that we don't feel justifies the benefits. **Upon acceptance of a PR, you must assign it a milestone.** @@ -385,31 +381,31 @@ _It's easier to release often._ 1. Decide whether this is a `patch`, `minor`, or `major` release. 1. Checkout `master` in your working copy & pull. 1. Modify `CHANGELOG.md`; follow the existing conventions in that file. - Use the "pull request" number, unless there isn't one. - _You do not need to add Markdown links; this is done automatically._ + Use the "pull request" number, unless there isn't one. + _You do not need to add Markdown links; this is done automatically._ 1. You can omit stuff from `CHANGELOG.md` that was done by a maintainer, but would have no interest to consumers of Mocha. 1. If the changes aren't of interest to consumers but _were not_ made by a maintainer, reference them anyway. - It's cool to give attribution! + It's cool to give attribution! 1. Use `npm version` (use `npm@8+`) to bump the version; see `npm version --help` for more info. - (Hint--use `-m`: e.g., `npm version patch -m 'Release v%s'`) + (Hint--use `-m`: e.g., `npm version patch -m 'Release v%s'`) 1. This command will update the list of authors (from the Git history) in `AUTHORS`, and add GitHub links to `CHANGELOG.md`. 1. These changes are then added to the Git "stage" and will be added to the commit. 1. Push `master` to `origin` with your new tag; e.g. `git push origin master --tags` 1. Copy & paste the `CHANGELOG.md` lines to a new GitHub "release". - Save release as draft. + Save release as draft. 1. Meanwhile, you can check [the build](https://travis-ci.org/mochajs/mocha) on Travis-CI and [GitHub Actions](https://github.com/mochajs/mocha/actions?query=workflow%3A%22Windows+CI%22). 1. Once the build is green, you'll want to trigger an update of `mochajs.org`: 1. _If you're doing a prerelease_, fast-forward the `next` branch to `master`, and push it. - This updates [https://next.mochajs.org](https://next.mochajs.org). - That's all. + This updates [https://next.mochajs.org](https://next.mochajs.org). + That's all. 1. _If this is NOT a prerelease_, fast-forward the `mochajs.org` branch to `master` and push it. - This updates [https://mochajs.org](https://mochajs.org). + This updates [https://mochajs.org](https://mochajs.org). 1. _If this is a "final" release_ (the first release of a major _after_ one or more prereleases) then remove the `next` tag from npm via `npm dist-tag rm next`. 1. Finally, you're satisfied with the release notes, open your draft release on GitHub, then click "publish." 1. Back in your working copy, run `npm publish`. - _If you're doing a prerelease, ensure that you use `--tag=next`._ + _If you're doing a prerelease, ensure that you use `--tag=next`._ 1. Announce the update on Twitter or just tell your dog or something. - New releases will be automatically tweeted by [@b0neskull](https://twitter.com/b0neskull) via a feed subscription to Mocha's "releases" page on GitHub. + New releases will be automatically tweeted by [@b0neskull](https://twitter.com/b0neskull) via a feed subscription to Mocha's "releases" page on GitHub. _Note: there are too many steps above._ From fca10d54dcbc5ad583ce3edec44dd98284e42965 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Tue, 5 Dec 2023 12:47:47 -0500 Subject: [PATCH 4/7] Update Gitter to Discord --- .github/CONTRIBUTING.md | 6 +++--- .github/ISSUE_TEMPLATE/config.yml | 6 +++--- MAINTAINERS.md | 12 ++++++------ README.md | 10 +++++----- docs/API.md | 2 +- docs/images/join-chat.svg | 2 +- docs/index.md | 8 ++++---- lib/cli/cli.js | 4 ++-- package.json | 2 +- 9 files changed, 26 insertions(+), 26 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 76f1b9f486..daab8260bf 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -4,7 +4,7 @@ ## ❓ Got a Question? -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). +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 Discord](https://discord.gg/KeDn2uXhER). ## ✏️ Filing Issues @@ -70,7 +70,7 @@ _Excellent._ Here's how: We could use your help bringing everyone together in peace and harmony. Please contact an [org member](https://github.com/orgs/mochajs/people). - **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 the [main chat room](https://gitter.im/mochajs/mocha)? +- **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 @@ -133,4 +133,4 @@ Now that the pull request exists, some tasks will be run on it: 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). -Join us in the [contributors' chat](https://gitter.im/mochajs/contributors)! +Join us in [our Discord](https://discord.gg/KeDn2uXhER)! diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index d07b80847e..dbdd514b0c 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -6,9 +6,9 @@ contact_links: - name: Documentation Website > APIs about: If you're using Mocha's API, see also the website's API docs. url: https://mochajs.org/api - - name: Gitter Chat - about: Our chat room is the right place for quick informal questions. - url: http://gitter.im/mochajs/mocha + - name: Discord + about: Our Discord is the right place for quick informal questions. + url: https://discord.gg/KeDn2uXhER - name: StackOverflow about: For more questions, see the `mocha` tag on StackOverflow. url: https://stackoverflow.com/questions/tagged/mocha diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 98b07d5455..6accddc8ab 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -28,9 +28,9 @@ A user interacts with the software, web site, documentation, etc., which these c As a user, you're expected to follow the [code of conduct](https://github.com/mochajs/mocha/blob/master/.github/CODE_OF_CONDUCT.md) when interacting in Mocha's "official" social spaces. This includes: -- Any chatroom under the `mochajs` organization on Gitter +- Any channel under the `mochajs` Discord - Any project under the `mochajs` organization on GitHub -- Any future social, in-person or online events which Mocha might organize +- Any future social, in-person, or online events which Mocha might organize ### Contributor @@ -43,7 +43,7 @@ Contributions include (but are not limited to): 1. Reporting bugs which follow the reporting guidelines 1. Suggesting and debating enhancements that have wide applicability -1. Helping others with Mocha-related questions on [Gitter](https://gitter.im/mochajs/mocha), [StackOverflow](https://stackoverflow.com), Google groups, or other sites +1. Helping others with Mocha-related questions on [our Discord](https://discord.gg/KeDn2uXhER), [StackOverflow](https://stackoverflow.com), or other sites 1. Sending pull requests which fix bugs, improve documentation, improve developer experience, improve code quality, and/or implement requested enhancements 1. Reviewing code on pull requests 1. Providing design assets @@ -148,8 +148,8 @@ The rest of the team won't wait on feedback that isn't necessarily forthcoming! ## Communication -Maintainers will mainly gather in [the mochajs/contributors channel](https://gitter.im/mochajs/contributors). -This is a _public_ channel, and _anyone_ can join. +Maintainers will mainly gather in the [Mocha Discord](https://discord.gg/KeDn2uXhER). +This is a _public_ Discord, and _anyone_ can join. Videoconference (or audio) calls may happen on a regular or irregular basis, as schedules allow. This is mainly because we have Real Lives and time zones suck. @@ -425,4 +425,4 @@ Expense transparency is built in to OpenCollective. --- -Questions? Ask in the [contributors' chat room](https://gitter.im/mochajs/contributors)! +Questions? Ask in the [Mocha Discord](https://discord.gg/KeDn2uXhER)! diff --git a/README.md b/README.md index d789264160..657df54ddc 100644 --- a/README.md +++ b/README.md @@ -8,9 +8,9 @@ GitHub Actions Build Status Coverage Status FOSSA Status -Gitter -OpenCollective -OpenCollective +Chat - Discord +OpenCollective Sponsors +OpenCollective Backers

@@ -27,7 +27,7 @@ - [Code of Conduct](https://github.com/mochajs/mocha/blob/master/.github/CODE_OF_CONDUCT.md) - [Contributing](https://github.com/mochajs/mocha/blob/master/.github/CONTRIBUTING.md) - [Development](https://github.com/mochajs/mocha/blob/master/.github/DEVELOPMENT.md) -- [Gitter Chatroom](https://gitter.im/mochajs/mocha) (ask questions here!) +- [Discord](https://discord.gg/KeDn2uXhER) (ask questions here!) - [Issue Tracker](https://github.com/mochajs/mocha/issues) ## Backers @@ -61,7 +61,7 @@ You might want to help: - Mocha could use a hand with [these issues](https://github.com/mochajs/mocha/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) - The [maintainer's handbook](https://github.com/mochajs/mocha/blob/master/MAINTAINERS.md) explains how things get done -Finally, come [chat with the maintainers](https://gitter.im/mochajs/contributors) on Gitter if you want to help with: +Finally, come [chat with the maintainers on Discord](https://discord.gg/KeDn2uXhER) if you want to help with: - Triaging issues, answering questions - Review, merging, and closing pull requests diff --git a/docs/API.md b/docs/API.md index 573a56fe3e..7b63a6b433 100644 --- a/docs/API.md +++ b/docs/API.md @@ -15,5 +15,5 @@ Otherwise, **you probably want the [main documentation](https://mochajs.org)**. - **[Main Documentation](https://mochajs.org)** - **[Release Notes / History / Changes](https://github.com/mochajs/mocha/blob/master/CHANGELOG.md)** - [Code of Conduct](https://github.com/mochajs/mocha/blob/master/.github/CODE_OF_CONDUCT.md) -- [Gitter Chatroom](https://gitter.im/mochajs/mocha) (ask questions here!) +- [Discord](https://discord.gg/KeDn2uXhER) (ask questions here!) - [Issue Tracker](https://github.com/mochajs/mocha/issues) diff --git a/docs/images/join-chat.svg b/docs/images/join-chat.svg index 0edf5f3b1e..eebaa8344c 100644 --- a/docs/images/join-chat.svg +++ b/docs/images/join-chat.svg @@ -1 +1 @@ -gittergitterjoin chatjoin chat \ No newline at end of file +chatchatDiscordDiscord diff --git a/docs/index.md b/docs/index.md index 2d9177d79e..64470af279 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,7 +7,7 @@ description: 'Mocha is a feature-rich JavaScript test framework running on Node. Mocha is a feature-rich JavaScript test framework running on [Node.js][] and in the browser, making asynchronous testing _simple_ and _fun_. Mocha tests run serially, allowing for flexible and accurate reporting, while mapping uncaught exceptions to the correct test cases. Hosted on [GitHub][github-mocha].

@@ -1777,7 +1777,7 @@ describe('Array', function () { it('should not throw an error', function () { (function () { [1, 2, 3].indexOf(4); - }.should.not.throw()); + }).should.not.throw(); }); it('should return -1', function () { [1, 2, 3].indexOf(4).should.equal(-1); @@ -2346,7 +2346,7 @@ $ npm test ## More Information -In addition to chatting with us on [Gitter][gitter-mocha], for additional information such as using +In addition to chatting with us on [our Discord][discord-mocha], for additional information such as using spies, mocking, and shared behaviours be sure to check out the [Mocha Wiki][mocha-wiki] on GitHub. For a running example of Mocha, view [example/tests.html](example/tests.html). For the JavaScript API, view the [API documentation](api/) or the [source](https://github.com/mochajs/mocha/blob/master/lib/mocha.js). @@ -2359,6 +2359,7 @@ or the [source](https://github.com/mochajs/mocha/blob/master/lib/mocha.js). [caniuse-promises]: https://caniuse.com/#feat=promises [chai]: https://www.chaijs.com/ [connect-test-output]: https://github.com/senchalabs/connect/blob/90a725343c2945aaee637e799b1cd11e065b2bff/tests.md +[discord-mocha]: https://discord.gg/KeDn2uXhER [emacs]: https://www.gnu.org/software/emacs/ [emacs-mocha.el]: https://github.com/scottaj/mocha.el [example-babel]: https://github.com/mochajs/mocha-examples/tree/master/packages/babel @@ -2376,7 +2377,6 @@ or the [source](https://github.com/mochajs/mocha/blob/master/lib/mocha.js). [github-mocha]: https://github.com/mochajs/mocha [gist-async-hooks]: https://gist.github.com/boneskull/7fe75b63d613fa940db7ec990a5f5843 [gist-globbing-tutorial]: https://gist.github.com/reggi/475793ea1846affbcfe8 -[gitter-mocha]: https://gitter.im/mochajs/mocha [jetbrains]: https://www.jetbrains.com/ [jetbrains-plugin]: https://www.jetbrains.com/idea/features/nodejs.html [mdn-array-sort]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort diff --git a/lib/cli/cli.js b/lib/cli/cli.js index 977a341564..b1b5354081 100755 --- a/lib/cli/cli.js +++ b/lib/cli/cli.js @@ -23,7 +23,7 @@ const { const lookupFiles = require('./lookup-files'); const commands = require('./commands'); const ansi = require('ansi-colors'); -const {repository, homepage, version, gitter} = require('../../package.json'); +const {repository, homepage, version, discord} = require('../../package.json'); const {cwd} = require('../utils'); /** @@ -68,7 +68,7 @@ exports.main = (argv = process.argv.slice(2), mochaArgs) => { .wrap(process.stdout.columns ? Math.min(process.stdout.columns, 80) : 80) .epilog( `Mocha Resources - Chat: ${ansi.magenta(gitter)} + Chat: ${ansi.magenta(discord)} GitHub: ${ansi.blue(repository.url)} Docs: ${ansi.yellow(homepage)} ` diff --git a/package.json b/package.json index 6da18b5cb8..10500e70ee 100644 --- a/package.json +++ b/package.json @@ -27,7 +27,7 @@ "bugs": { "url": "https://github.com/mochajs/mocha/issues/" }, - "gitter": "https://gitter.im/mochajs/mocha", + "discord": "https://discord.gg/KeDn2uXhER", "homepage": "https://mochajs.org/", "logo": "https://cldup.com/S9uQ-cOLYz.svg", "notifyLogo": "https://ibin.co/4QuRuGjXvl36.png", From 79afdeeb7231465936eba8c87da7d704841b9553 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Tue, 12 Dec 2023 11:07:45 -0500 Subject: [PATCH 5/7] Add 'I want to provide a PR' optional checkboxes --- .github/ISSUE_TEMPLATE/01-bug.yml | 1 + .github/ISSUE_TEMPLATE/02-documentation.yml | 1 + .github/ISSUE_TEMPLATE/03-feature-request.yml | 1 + .github/ISSUE_TEMPLATE/04-repository-tooling.yml | 1 + 4 files changed, 4 insertions(+) diff --git a/.github/ISSUE_TEMPLATE/01-bug.yml b/.github/ISSUE_TEMPLATE/01-bug.yml index 2202b31280..2e4e83b673 100644 --- a/.github/ISSUE_TEMPLATE/01-bug.yml +++ b/.github/ISSUE_TEMPLATE/01-bug.yml @@ -9,6 +9,7 @@ body: required: true - label: I have 'smoke tested' the code to be tested by running it outside the real test suite to get a better sense of whether the problem is in the code under test, my usage of Mocha, or Mocha itself. required: true + - label: I want to provide a PR to resolve this type: checkboxes - attributes: description: What did you expect to happen? diff --git a/.github/ISSUE_TEMPLATE/02-documentation.yml b/.github/ISSUE_TEMPLATE/02-documentation.yml index 75f790fad5..ed8b54f986 100644 --- a/.github/ISSUE_TEMPLATE/02-documentation.yml +++ b/.github/ISSUE_TEMPLATE/02-documentation.yml @@ -7,6 +7,7 @@ body: required: true - label: I have searched for [related issues](https://github.com/mochajs/mocha/issues?q=is%3Aissue) and [issues with the `faq` label](https://github.com/mochajs/mocha/issues?utf8=%E2%9C%93&q=is%3Aissue%20label%3Afaq%20), but none matched my issue. required: true + - label: I want to provide a PR to resolve this type: checkboxes - attributes: description: What would you like to report? diff --git a/.github/ISSUE_TEMPLATE/03-feature-request.yml b/.github/ISSUE_TEMPLATE/03-feature-request.yml index 2ecb652434..1179b25018 100644 --- a/.github/ISSUE_TEMPLATE/03-feature-request.yml +++ b/.github/ISSUE_TEMPLATE/03-feature-request.yml @@ -7,6 +7,7 @@ body: required: true - label: I have searched for [related issues](https://github.com/mochajs/mocha/issues?q=is%3Aissue) and [issues with the `faq` label](https://github.com/mochajs/mocha/issues?utf8=%E2%9C%93&q=is%3Aissue%20label%3Afaq%20), but none matched my issue. required: true + - label: I want to provide a PR to resolve this type: checkboxes - attributes: description: What is the feature gap or problem you'd like to address? diff --git a/.github/ISSUE_TEMPLATE/04-repository-tooling.yml b/.github/ISSUE_TEMPLATE/04-repository-tooling.yml index f79fe7ce50..6b37f93225 100644 --- a/.github/ISSUE_TEMPLATE/04-repository-tooling.yml +++ b/.github/ISSUE_TEMPLATE/04-repository-tooling.yml @@ -11,6 +11,7 @@ body: required: true - label: I have searched for [related issues](https://github.com/mochajs/mocha/issues?q=is%3Aissue) and [issues with the `faq` label](https://github.com/mochajs/mocha/issues?utf8=%E2%9C%93&q=is%3Aissue%20label%3Afaq%20), but none matched my issue. required: true + - label: I want to provide a PR to resolve this type: checkboxes - attributes: description: What did you expect to be able to do? From 5cecbec90e8cb8d2004c38895cb3d1b7be403373 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Tue, 26 Dec 2023 23:18:17 -0500 Subject: [PATCH 6/7] Updated issue templates --- .github/CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index daab8260bf..01a3e10139 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -19,7 +19,7 @@ This includes bugs, feature requests, and improvements to documentation. Sorry! It happens to the best of us. -Please [file an issue using the bug report template](https://github.com/mochajs/mocha/issues/new?assignees=&labels=unconfirmed-bug&projects=&template=bug_report.md) with _as much detail as possible_ to help us reproduce and diagnose the bug. +Please [file an issue using the bug report template](https://github.com/mochajs/mocha/issues/new?assignees=&labels=type%3A+bug&projects=&template=01-bug.yml&title=%F0%9F%90%9B+Bug%3A+%3Cshort+description+of+the+bug%3E) with _as much detail as possible_ to help us reproduce and diagnose the bug. Most importantly: - Let us know _how_ you're running Mocha (options, flags, environment, browser or Node.js, etc.). @@ -31,7 +31,7 @@ If you don't within a few weeks, your issue will be closed for inactivity. ### ❗️ Propose a Change -Please [file an issue using the feature request template](https://github.com/mochajs/mocha/issues/new?assignees=&labels=feature&projects=&template=feature_request.md&title=). +Please [file an issue using the feature request template](https://github.com/mochajs/mocha/issues/new?assignees=&labels=type%3A+feature&projects=&template=03-feature-request.yml&title=%F0%9F%9A%80+Feature%3A+%3Cshort+description+of+the+feature%3E). Most importantly: - Let us know _what_ the proposed change is, in as much detail as you can From 71428326e8b9d1f4c056ff57b2666e4151571183 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Tue, 26 Dec 2023 23:19:09 -0500 Subject: [PATCH 7/7] Shorter name for Docs --- .github/ISSUE_TEMPLATE/02-documentation.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/02-documentation.yml b/.github/ISSUE_TEMPLATE/02-documentation.yml index ed8b54f986..9f70afc940 100644 --- a/.github/ISSUE_TEMPLATE/02-documentation.yml +++ b/.github/ISSUE_TEMPLATE/02-documentation.yml @@ -22,5 +22,5 @@ body: description: Report a typo or missing area of documentation labels: - "area: documentation" -name: 📝 Documentation -title: "📝 Documentation: " +name: 📝 Docs +title: "📝 Docs: "