docs: update documentation

Author: Xunnamius

CONTRIBUTING.md

@@ -8,8 +8,9 @@ series [How to Contribute to an Open Source Project on GitHub][egghead]
 ## Project Setup
 
 1. Fork and clone the repo.
-2. `$ npm install` to install dependencies.
-3. `$ npm run validate` to validate you've got it working.
+2. `$ npm ci` to install dependencies without affecting the `package-lock.json`
+   file.
+3. `$ npm run test` to validate you've got it working.
 4. Create a branch for your PR.
 
 > Tip: Keep your `master` branch pointing at the original repository and make
@@ -29,15 +30,21 @@ series [How to Contribute to an Open Source Project on GitHub][egghead]
 
 ## Committing and Pushing Changes
 
-Please make sure to run the tests before you commit your changes. You can run
-`npm run test:update` which will update any snapshots that need updating. Make
-sure to include those changes (if they exist) in your commit.
+Please make sure to run the unit _and integration_ tests before you send your
+PR. You can do so by running `npm run test:all`, which will run all possible
+tests. On some Windows/WSL systems, the concurrent integration tests can be
+unstable, so set the environment variable `NO_CONCURRENT=true` to run the tests
+serially (which will be slow) if you encounter strange errors.
+
+Also, this project comes with Husky git hooks that run unit tests, linters, and
+formatters on the source before each commit. To prevent your contributions from
+being rejected, avoid circumventing these git hooks.
 
 ## Help Needed
 
-Please checkout the [the open issues][issues]
+Please checkout the [the open issues][issues].
 
-Also, please watch the repo and respond to questions/bug reports/feature
+Also, please watch the repo and respond to questions, bug reports, and feature
 requests! Thanks!
 
 <!-- prettier-ignore-start -->

MAINTAINING.md

@@ -4,8 +4,8 @@ This is documentation for maintainers of this project.
 
 ## Code of Conduct
 
-Please review, understand, and be an example of it. Violations of the code of
-conduct are taken seriously, even (especially) for maintainers.
+Please [review][1], understand, and be an example of it. Violations of the code
+of conduct are taken seriously, even (especially) for maintainers.
 
 ## Issues
 
@@ -16,7 +16,7 @@ minimal reproduction of what they're trying to accomplish or the bug they think
 they've found.
 
 Once it's determined that a code change is necessary, point people to
-[makeapullrequest.com][1] and invite them to make a pull request. If they're the
+[makeapullrequest.com][2] and invite them to make a pull request. If they're the
 one who needs the feature, they're the one who can build it. If they need some
 hand holding and you have time to lend a hand, please do so. It's an investment
 into another human being, and an investment into a potential maintainer.
@@ -32,79 +32,90 @@ As a maintainer, you're fine to make your branches on the main repo or on your
 own fork. Either way is fine.
 
 When we receive a pull request, a GitHub Actions build is kicked off
-automatically (see [`.github/workflows`][2]). We avoid merging anything that
+automatically (see [`.github/workflows`][3]). We avoid merging anything that
 fails the Actions workflow.
 
 Please review PRs and focus on the code rather than the individual. You never
 know when this is someone's first ever PR and we want their experience to be as
 positive as possible, so be uplifting and constructive.
 
-When you merge the pull request, 99% of the time you should use the [Squash and
-merge][3] feature. This keeps our git history clean, but more importantly, this
-allows us to make any necessary changes to the commit message so we release what
-we want to release. See the next section on Releases for more about that.
+When you merge the pull request, 99% of the time you should use the [rebase and
+merge][4] feature. This keeps our git history clean. If commit messages need to
+be adjusted, maintainers should force push new commits with adjusted messages to
+the PR branch before merging it in.
+
+The [squash and merge][5] feature can also be used, but keep in mind that
+squashing commits will likely damage the [generated][6] [CHANGELOG.md][7],
+hinder [bisection][8], and result in [non-atomic commits][9], so use it
+sparingly.
 
 ## Release
 
 Our releases are automatic. They happen whenever code lands into `master`. A
-GitHub Actions build gets kicked off and if it's successful, a tool called
-[`semantic-release`][4] is used to automatically publish a new release to npm as
-well as a changelog to GitHub. It is only able to determine the version and
-whether a release is necessary by the git commit messages. With this in mind,
-**please brush up on [the commit message convention][commit] which drives our
-releases.**
-
-> One important note about this: Please make sure that commit messages do NOT
+GitHub Actions build gets kicked off and, if it's successful, a tool called
+[`semantic-release`][10] is used to automatically publish a new release to npm
+and GitHub along with an updated changelog. It is only able to determine the
+version and whether a release is necessary by the git commit messages. With this
+in mind, **please brush up on [the commit message convention][commit] which
+drives our releases.**
+
+> One important note about this: please make sure that commit messages do NOT
 > contain the words "BREAKING CHANGE" in them unless we want to push a major
 > version. I've been burned by this more than once where someone will include
-> "BREAKING CHANGE: None" and it will end up releasing a new major version. Not
-> a huge deal honestly, but kind of annoying...
+> "BREAKING CHANGE: None" and it will end up releasing a new major version. Do
+> not do this!
 
 ### Manual Releases
 
-This project has an automated release set up. So things are only released when
-there are useful changes in the code that justify a release. But sometimes
-things get messed up one way or another and we need to trigger the release
-ourselves. When this happens, simply bump the number below and commit that with
-the following commit message based on your needs:
+This project has an automated release set up. That means things are only
+released when there are useful changes in the code that justify a release. See
+[the release rules][11] for a list of commit types that trigger releases.
 
-#### Major
+However, sometimes things get messed up (e.g. CI workflow / GitHub Actions
+breaks) and we need to trigger a release ourselves. When this happens,
+semantic-release can be triggered locally by following these steps:
 
-```text
-fix(release): manually release a major version
+> If one of these steps fails, you should address the failure before running the
+> next step.
 
-There was an issue with a major release, so this manual-releases.md
-change is to release a new major version.
+```bash
+# These command must be run from the project root
 
-Reference: #<the number of a relevant pull request, issue, or commit>
+# 1. Setup the local environment. Add your auth tokens to this file
+# ! DO NOT COMMIT THIS FILE !
+cp .env.default .env
 
-BREAKING CHANGE: <mention any relevant breaking changes (this is what triggers the major version change so don't skip this!)>
-```
+# 2. Reset the working directory to a clean state (deletes all ignored files)
+npm run clean
 
-#### Minor
+# 3. Lint all files
+npm run lint:all
 
-```text
-feat(release): manually release a minor version
+# 4. Build distributables
+npm run build:dist
 
-There was an issue with a minor release, so this manual-releases.md
-change is to release a new minor version.
+# 5. Build auxiliary documentation
+npm run build:docs
 
-Reference: #<the number of a relevant pull request, issue, or commit>
-```
+# 6. Build any external executables (used in GitHub Actions workflows)
+npm run build:externals
 
-#### Patch
+# 7. Format all files
+npm run format
 
-```text
-fix(release): manually release a patch version
+# 8. Run all possible tests and generate coverage information
+npm run test:all
 
-There was an issue with a patch release, so this manual-releases.md
-change is to release a new patch version.
+# 9. Upload coverage information to codecov (only if you have the proper token)
+CODECOV_TOKEN=$(npx --yes dotenv-cli -p CODECOV_TOKEN) codecov
 
-Reference: #<the number of a relevant pull request, issue, or commit>
+# 10. Trigger semantic-release locally and generate a new release. This requires
+# having tokens for NPM and GitHub with the appropriate permissions. This
+# command should be run in a clean environment using a user account without a
+# home directory (so no ~/.npmrc or ~/.gnupg directories)
+NPM_TOKEN=$(npx --yes dotenv-cli -p NPM_TOKEN) GH_TOKEN=$(npx --yes dotenv-cli -p GITHUB_TOKEN) HUSKY=0 UPDATE_CHANGELOG=true GIT_AUTHOR_NAME=$(git config --global --get user.name) GIT_COMMITTER_NAME=$(git config --global --get user.name) GIT_AUTHOR_EMAIL=$(git config --global --get user.email) GIT_COMMITTER_EMAIL=$(git config --global --get user.email) npx --no-install semantic-release --no-ci --extends "$(pwd)/release.config.js"
 ```
 
-The number of times we've had to do a manual release is: 1
-
 <!-- lint ignore -->
 
 ## Thanks!
@@ -113,7 +124,18 @@ Thank you so much for helping to maintain this project!
 
 [commit]:
   https://github.com/conventional-changelog-archived-repos/conventional-changelog-angular/blob/ed32559941719a130bb0327f886d6a32a8cbc2ba/convention.md
-[1]: http://makeapullrequest.com
-[2]: ./.github/workflows
-[3]: https://help.github.com/articles/merging-a-pull-request
-[4]: https://github.com/semantic-release/semantic-release
+[1]: ./.github/CODE_OF_CONDUCT.md
+[2]: http://makeapullrequest.com
+[3]: ./.github/workflows
+[4]:
+  https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#rebase-and-merge-your-commits
+[5]:
+  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
+[6]: https://github.com/conventional-changelog/conventional-changelog
+[7]: https://www.conventionalcommits.org/en/v1.0.0
+[8]:
+  https://www.metaltoad.com/blog/beginners-guide-git-bisect-process-elimination
+[9]: https://dev.to/paulinevos/atomic-commits-will-help-you-git-legit-35i7
+[10]: https://github.com/semantic-release/semantic-release
+[11]:
+  https://github.com/babel-utils/babel-plugin-tester/blob/c13a2e0ff4ea9289d7a79a5da8949c125c636130/release.config.js#L27

README.md

@@ -1322,8 +1322,8 @@ pluginTester({
 
 ### Fixtures Examples
 
-See [`fixtures`][39] for an example directory layout or check out some of these
-other projects:
+See [`fixtures`][39] for an example directory layout or check out the use of
+babel-plugin-tester fixtures in some of these other projects:
 
 <!-- lint disable list-item-style -->