Master to trunk: secondary renames (docs and comments) (#24712)

Co-authored-by: Brad Jorsch <[email protected]>

.github/files/filter-mirrors-for-release-branch.sh

@@ -4,7 +4,7 @@
 #
 # Required:
 # - BUILD_BASE: Path to the build directory, which contains "mirrors.txt" and directories for each repo to mirror to.
-# - GITHUB_REF: Git ref being mirrored from, e.g. "refs/heads/master". Must begin with "refs/heads/".
+# - GITHUB_REF: Git ref being mirrored from, e.g. "refs/heads/trunk". Must begin with "refs/heads/".
 
 # Halt on error
 set -eo pipefail

.github/test-case-reminder.json

@@ -2,5 +2,5 @@
 	"tests_dir": "docs/testing/regression-checklist/test-suites/",
 	"mapping_file": "docs/testing/regression-checklist/mapping.json",
 	"tests_repo": "automattic/jetpack",
-	"comment_footer": "\n\nIf you think that suggestions should be improved please edit the configuration file [here](https://github.com/Automattic/jetpack/tree/master/docs/testing/regression-checklist/mapping.json). You can also modify/add [test-suites](https://github.com/Automattic/jetpack/tree/master/docs/testing/regression-checklist/test-suites) to be used in the configuration file."
+	"comment_footer": "\n\nIf you think that suggestions should be improved please edit the configuration file [here](https://github.com/Automattic/jetpack/tree/trunk/docs/testing/regression-checklist/mapping.json). You can also modify/add [test-suites](https://github.com/Automattic/jetpack/tree/trunk/docs/testing/regression-checklist/test-suites) to be used in the configuration file."
 }

.github/workflows/stale.yml

@@ -48,6 +48,6 @@ jobs:
             </ul>
 
             <p>No further action is needed. But it's worth checking if this PR has clear
-            testing instructions, is it up to date with master, and it is still valid.
+            testing instructions, is it up to date with trunk, and it is still valid.
             Feel free to close this PR if you think it's not valid anymore — if you
             do, please add a brief explanation.</p>

docs/coding-guidelines.md

@@ -14,7 +14,7 @@ These are some things to keep in mind when writing code for Jetpack plugin. Plea
 - Install PHP Code Sniffer [Code Sniffer rules for Jetpack Coding Standards.](https://github.com/Automattic/jetpack-codesniffer#usage) They will make it easier for you to notice any missing documentation or coding standards you should respect. Most IDEs display warnings and notices inside the editor, making it easy to inspect your code.
 - If coding a module, make sure you declare the module in the inline doc, [like this](https://github.com/Automattic/jetpack/blob/16bc2fce3ace760ff402f656dcf05255888f23f4/modules/sitemaps/sitemaps.php#L92-L101). The same applies for filters or actions, [as shown here](https://github.com/Automattic/jetpack/blob/16bc2fce3ace760ff402f656dcf05255888f23f4/modules/sitemaps/sitemaps.php#L143-L151).
 - Sanitize URLs, attributes, everything. WordPress.com VIP has this nice [article about the topic](https://wpvip.com/documentation/vip-go/validating-sanitizing-and-escaping/).
-- Create unit tests if you can ([here are the Jetpack plugin tests for reference](https://github.com/Automattic/jetpack/tree/master/projects/plugins/jetpack/tests)). If you're not familiar with Unit Testing, you can check [this tutorial](https://pippinsplugins.com/series/unit-tests-wordpress-plugins/).
+- Create unit tests if you can ([here are the Jetpack plugin tests for reference](https://github.com/Automattic/jetpack/tree/trunk/projects/plugins/jetpack/tests)). If you're not familiar with Unit Testing, you can check [this tutorial](https://pippinsplugins.com/series/unit-tests-wordpress-plugins/).
 
 ## Deprecating code
 

docs/development-environment.md

@@ -139,7 +139,7 @@ You'll need all the tools below to work in the Jetpack monorepo.
 
 * #### jetpack CLI
 
-	The `jetpack` CLI tool is used to help with development in the Jetpack monorepo. Find out more and install it by following the instructions on the [Jetpack CLI page](https://github.com/Automattic/jetpack/blob/master/tools/cli/README.md).
+	The `jetpack` CLI tool is used to help with development in the Jetpack monorepo. Find out more and install it by following the instructions on the [Jetpack CLI page](https://github.com/Automattic/jetpack/blob/trunk/tools/cli/README.md).
 
 ### Check if your environment is ready for Jetpack development
 
@@ -163,7 +163,7 @@ Once you have a local copy of Jetpack and all development tools installed, you c
 
 ## Building your project
 
-The Jetpack monorepo is home to different projects, with different needs. Some require that you build PHP, JavaScript, and CSS components. [The Jetpack CLI tool](https://github.com/Automattic/jetpack/blob/master/tools/cli/README.md) will help you with all building steps.
+The Jetpack monorepo is home to different projects, with different needs. Some require that you build PHP, JavaScript, and CSS components. [The Jetpack CLI tool](https://github.com/Automattic/jetpack/blob/trunk/tools/cli/README.md) will help you with all building steps.
 
 There are different types of builds:
 
@@ -193,7 +193,7 @@ There are different types of builds:
 # Unit-testing
 
 
-The Jetpack plugin includes several [unit tests](https://github.com/Automattic/jetpack/tree/master/projects/plugins/jetpack/tests) that you can run in your local environment before submitting a new Pull Request.
+The Jetpack plugin includes several [unit tests](https://github.com/Automattic/jetpack/tree/trunk/projects/plugins/jetpack/tests) that you can run in your local environment before submitting a new Pull Request.
 
 If you're not familiar with PHP Unit Testing, you can also check [this tutorial](https://pippinsplugins.com/series/unit-tests-wordpress-plugins/)
 

docs/git-workflow.md

@@ -2,7 +2,7 @@
 
 ## Branch Naming Scheme
 
-All changes should be developed in a new branch created from the `master` branch.
+All changes should be developed in a new branch created from the `trunk` branch.
 
 Branches use the following naming conventions:
 
@@ -11,7 +11,7 @@ Branches use the following naming conventions:
 * `fix/{something}` -- When you are fixing something broken in a feature
 * `try/{something}` -- When you are trying out an idea and want feedback
 
-For example, you can run: `git checkout master` and then `git checkout -b fix/whatsits` to create a new `fix/whatsits` branch off of `origin/master`.
+For example, you can run: `git checkout trunk` and then `git checkout -b fix/whatsits` to create a new `fix/whatsits` branch off of `origin/trunk`.
 
 The Jetpack repo uses the following "reserved" branch name conventions:
 
@@ -25,16 +25,16 @@ The Jetpack repo uses the following "reserved" branch name conventions:
 
 ## Keeping Your Branch Up To Date
 
-There are two ways to update your branch with changes to `master` or a parent PR.
+There are two ways to update your branch with changes to `trunk` or a parent PR.
 
-1. **Merge:** After a `git fetch`, execute `git merge origin/master` (or `git merge origin/yourbranchname` for a parent PR) to pull in the latest changes. If there are conflicts, you'll need to resolve them by hand and then commit manually.
+1. **Merge:** After a `git fetch`, execute `git merge origin/trunk` (or `git merge origin/yourbranchname` for a parent PR) to pull in the latest changes. If there are conflicts, you'll need to resolve them by hand and then commit manually.
    * Pro: GitHub deals with this much better.
    * Pro: Collaborators can just `git pull` to update their local copy of the branch.
    * Con: Can lead to a messy-looking history while the branch is in progress. Since we use "squash and merge" to commit PRs, though, this isn't an issue once the PR is finally accepted.
    * Con: If there's a conflict while merging, you might wind up having to commit the merge commit with `--no-verify` to avoid our pre-commit hook complaining about things.
    * Note: To get a clean view of the branch's history, use `git log --first-parent`.
-   * Note: To get a clean diff of the branch versus master, like what GitHub shows, use `git diff origin/master...HEAD` (note the three dots).
-2. **[Rebase](https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request):** Execute `git pull --rebase origin master` (or `git pull --rebase origin yourbranchname` for a parent PR), or do a `git fetch` then execute `git rebase origin/master` (or `git rebase origin/yourbranchname`). It will reapply each patch, and if there are conflicts at any step you'll have to resolve them by hand and then `git rebase --continue`.
+   * Note: To get a clean diff of the branch versus trunk, like what GitHub shows, use `git diff origin/trunk...HEAD` (note the three dots).
+2. **[Rebase](https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request):** Execute `git pull --rebase origin trunk` (or `git pull --rebase origin yourbranchname` for a parent PR), or do a `git fetch` then execute `git rebase origin/trunk` (or `git rebase origin/yourbranchname`). It will reapply each patch, and if there are conflicts at any step you'll have to resolve them by hand and then `git rebase --continue`.
    * Pro: Keeps the branch's history cleaner.
    * Con: GitHub doesn't handle it very well. It may lose inline comments on the pre-rebase commits, and it will remove the old commit entries from the conversation (making it harder to determine the state of the PR when earlier comments were left) and instead show every one in the rebase as being "added" again at the time that the rebase was pushed.
    * Con: Anyone else who has checked out your branch pre-rebase can't just `git pull`.
@@ -49,9 +49,9 @@ If you're working on a collaborative branch, it's also a good idea to rebase you
 
 If you're a contributor and have forked the Jetpack repository, you may need to follow some git steps to keep your PRs up to date.
 
-* We can usually ask you to "rebase against latest master" in these situations.
+* We can usually ask you to "rebase against latest trunk" in these situations.
 
-  1. Your PR has conflicts due to some recent changes in Jetpack master.
+  1. Your PR has conflicts due to some recent changes in Jetpack trunk.
   2. We changed code in the unit tests setup or dependencies and thus we need you to update your PR so we can run automated tests on your code.
 
 If we eventually ask you that, here are the commands that may help you achieve it.
@@ -64,10 +64,10 @@ $ git remote add jetpack [email protected]:Automattic/jetpack.git
 # Checkout to the branch you're working on locally
 $ git checkout update/my-changes
 
-# Ask git to bring in the changes that are currently on original Jetpack repo's master branch and
+# Ask git to bring in the changes that are currently on original Jetpack repo's trunk branch and
 # put them in your local copy of the repo before your commits.
 $ git fetch jetpack
-$ git rebase jetpack/master
+$ git rebase jetpack/trunk
 
 # Make more changes and commit OR resolve conflicts.
 # Then push your changes to your forked version of Jetpack
@@ -78,10 +78,10 @@ $ git push -f origin update/my-changes
 
 #### Dealing with lock files
 
-It's seldom worth manually merging changes to lock files. It's usually better to regenerate the changes instead. Assuming you've just done a `git merge origin/master`,
+It's seldom worth manually merging changes to lock files. It's usually better to regenerate the changes instead. Assuming you've just done a `git merge origin/trunk`,
 
-* For `composer.lock`, you can do something like `git checkout origin/master projects/x/y/composer.lock && tools/composer-update-monorepo.sh --root-reqs projects/x/y/`.
-* For `pnpm-lock.yaml`, you can do `git checkout origin/master pnpm-lock.yaml && pnpm install`.
+* For `composer.lock`, you can do something like `git checkout origin/trunk projects/x/y/composer.lock && tools/composer-update-monorepo.sh --root-reqs projects/x/y/`.
+* For `pnpm-lock.yaml`, you can do `git checkout origin/trunk pnpm-lock.yaml && pnpm install`.
 
 For the pnpm lock file in particular, it's easy for a `git merge` or `git rebase` to do weird things resulting in a diff with unnecessary changes or outdated versions of indirect dependencies.
 

docs/guides/report-bugs.md

@@ -50,7 +50,7 @@ If you believe you've come across a bug and you've worked through all the steps
 
 You should also check to see if the potential bug is limited to one browser; this is especially important for any bugs that may be Javascript or jQuery-related, as some browsers are more likely to experience those issues than others.
 
-See which browsers Jetpack supports from [coding guidelines](../coding-guidelines.md#versions-supported) or from the [`package.json`](https://github.com/Automattic/jetpack/blob/master/package.json) file.
+See which browsers Jetpack supports from [coding guidelines](../coding-guidelines.md#versions-supported) or from [the `@wordpress/browserslist-config` package](https://www.npmjs.com/package/@wordpress/browserslist-config).
 
 ## Contribute and comment on existing issues
 

docs/monorepo.md

@@ -157,7 +157,7 @@ A project must define `.scripts.build-development` and/or `.scripts.build-produc
 The build commands should assume that `pnpm install` and `composer install` have already been run, and _must not_ run them again.
 
 * If you're building JavaScript bundles with Webpack and [@automattic/jetpack-webpack-config](../projects/js-packages/webpack-config/README.md), note that your build-production command should set `NODE_ENV=production` and `BABEL_ENV=production`.
-* If you run into problems with Composer not recognizing the local git branch as being the right version, try setting `COMPOSER_ROOT_VERSION=dev-master` in the environment.
+* If you run into problems with Composer not recognizing the local git branch as being the right version, try setting `COMPOSER_ROOT_VERSION=dev-trunk` in the environment.
 * When building for the mirror repos, note that `COMPOSER_MIRROR_PATH_REPOS=1` will be set in the environment and the list of repositories in `composer.json` may be altered.
   This is not normally done in development environments, even with `jetpack build --production`.
 * For a production build of a plugin, `composer install` is passed `-o --no-dev --classmap-authoritative --prefer-dist`. For development builds and for production builds of non-plugin projects, no options are passed.
@@ -232,7 +232,7 @@ We currently make use of the following packages in testing; it's encouraged to u
 
 WordPress plugins generally want to run within WordPress. All monorepo plugins are copied into place in a WordPress installation and tests are run from there.
 
-Tests will be run against the latest version of WordPress using the variety of supported PHP versions, and against the previous and master versions of WordPress using the PHP version in `.github/versions.sh`. The environment variable `WP_BRANCH` will be set to 'latest', 'previous', or 'master' accordingly. If you have tests that only need to be run once, run them when `WP_BRANCH` is 'latest'.
+Tests will be run against the latest version of WordPress using the variety of supported PHP versions, and against the previous and trunk versions of WordPress using the PHP version in `.github/versions.sh`. The environment variable `WP_BRANCH` will be set to 'latest', 'previous', or 'trunk' accordingly. If you have tests that only need to be run once, run them when `WP_BRANCH` is 'latest'.
 
 When implementing tests within a new plugin, you can follow the example set in [the example bootstrap.php](./examples/bootstrap.php).
 
@@ -262,7 +262,7 @@ Most projects in the monorepo should have a mirror repository holding a built ve
 
 1. Create the mirror repo on GitHub. It will most likely be named like "<span>https://</span>github.com/Automattic/jetpack-_something_".
    1. The repo's description should begin with `[READ ONLY]` and end with `This repository is a mirror, for issue tracking and development head to: https://github.com/automattic/jetpack`.
-   2. The default branch should be `master`, matching the monorepo.
+   2. The default branch should be `trunk`, matching the monorepo.
    3. In the repo's settings, turn off wikis, issues, projects, and so on.
    4. Make sure that [matticbot](https://github.com/matticbot) can push to the repo.
    5. Make sure that Actions are enabled. The build process copies workflows from `.github/files/mirror-.github` into the mirror to do useful things like automatically close PRs with a reference back to the monorepo.
@@ -275,7 +275,7 @@ Most projects in the monorepo should have a mirror repository holding a built ve
 
 ### Autotagger
 
-If `.extra.autotagger` is set to a truthy value in the project's `composer.json`, a GitHub Action will be included in the mirror repo that will read the most recent version from the mirrored `CHANGELOG.md` in each push to master, and create the tag if that version has no prerelease or build suffix.
+If `.extra.autotagger` is set to a truthy value in the project's `composer.json`, a GitHub Action will be included in the mirror repo that will read the most recent version from the mirrored `CHANGELOG.md` in each push to trunk, and create the tag if that version has no prerelease or build suffix.
 
 If `.extra.autotagger` is set to an object with a truthy value for `major` (i.e. if `.extra.autotagger.major` is truthy), the GitHub Action will additionally create or update a major-version tag as is common for GitHub Action repositories.
 
@@ -285,13 +285,13 @@ Note that, for this to work, you'll need to create a secret `API_TOKEN_GITHUB` i
 
 This is intended to work in combination with [Changelogger](#jetpack-changelogger): When any change files are present in the project, a `-alpha` version entry will be written to the changelog so the autotagging will not be triggered. To release a new version, you'd do the following:
 
-1. (optional) Go to the [monorepo's branch settings page](https://github.com/Automattic/jetpack/settings/branches), and turn on "Require branches to be up to date before merging" for the master branch.
+1. (optional) Activate the "Release Lock" (see PCYsg-zQS-p2#generating-a-new-changelog).
 2. Use `tools/changelogger-release.sh` to create a PR rolling the change files into a new changelog entry.
 3. Push and merge that PR.
-4. If you turned on "Require branches to be up to date before merging" in step 1, go turn it off. If you didn't, check that no one merged any PRs in between steps 2 and 3 that added change files to the projects being released.
+4. If you used the Release Lock in step 1, go turn it off. If you didn't, check that no one merged any PRs in between steps 2 and 3 that added change files to the projects being released.
    * If they did, you'll likely have to create a release branch in the affected projects' mirror repos and manually tag.
-5. Verify that the Build workflow run for your PR's merge to master succeeded. [This search](https://github.com/Automattic/jetpack/actions/workflows/build.yml?query=branch%3Amaster) will show the runs of that workflow for all merges to master.
-   * If it failed, you can try re-running it as long as no other PRs were merged adding change files to the projects being released. If some were merged, you'll have to manually tag the affected projects.
+5. Verify that the Build workflow run for your PR's merge to trunk succeeded. [This search](https://github.com/Automattic/jetpack/actions/workflows/build.yml?query=branch%3Atrunk) will show the runs of that workflow for all merges to trunk.
+   * If it failed, you can try re-running it as long as no other PRs were merged. If some were merged, you'll have to manually tag the affected projects.
 
 ### Auto-release