Update release checklist and document branch management

Document some additional insights from releasing 4.0, as well as update for changed reality (like the wiki being maintained via PRs to the docs repo).

Author: jrfnl

.github/branch-management-for-majors.md

@@ -0,0 +1,33 @@
+# Checklists for branch management of majors
+
+Note: these lists may be incomplete and should be regarded as a starting point to be updated/enhanced each time new insights present themselves.
+
+
+## Stop support for old major
+
+- [ ] Remove "old major" from workflows in the **oldest major still supported**.
+    I.e. when support for 3.x will be stopped, `3.x` should be removed from the workflows in the `4.x` branch (not from the 3.x branch).
+- [ ] Update target branch in the `.github/dependabot.yml` file in the **oldest major still supported** to be that oldest major.
+- [ ] Update target branch (`BASE`) in the `.github/workflows/happy-new-year.yml` file in the **oldest major still supported** to be that oldest major.
+
+
+## Start branch for next major
+
+- [ ] Add "next major" to workflows in the **oldest major still supported**.
+    I.e. when a new 5.x branch will be created while 3.x still has minimal support, this change should be made in the `3.x` branch (otherwise in the 4.x branch).
+- [ ] Create x.x branch.
+
+In the new branch:
+- [ ] Change `Config::VERSION` to next major version number.
+- [ ] Change `Config::STABILITY` to `alpha`.
+- [ ] Create CHANGELOG-x.x.md file for the new major.
+- [ ] Add CHANGELOG for the _major before last_ to the `.gitattributes` `export-ignore`s.
+- [ ] Update branch references for the badges in the README.
+- [ ] Update installation instructions (`^4.0`) in the README.
+- [ ] Update branch reference/instructions in the issue and PR templates.
+- [ ] Update branch reference in the `bug_report.md` issue template.
+- [ ] Update branch reference in the `CONTRIBUTING` file ("Getting Started" section).
+    => For the previous four items, see 1433a86bd4bd3480048d485983e7f16f8e8ec981 as an example.
+- [ ] If the next major includes a PHP version drop, that should be the one of the first commits
+    Example: a7a27b9413106cf4bf10514d6ce93658899ec279
+    Also update relevant files from 19724954edc7997125040fbf84eddffca99d674f

.github/release-checklist.md

@@ -1,12 +1,14 @@
 # Release checklist
 
+**Important**: If releases for multiple branches are to be tagged, always tag the 3.x release first, 4.x second etc!
+
 ## Before Release
 
 ### General
 
-- [ ] Verify, and if necessary, update the version constraints for dependencies in the `composer.json` - PR #xxx
-- [ ] Verify that any new functions have type declarations (ClassName/array/callable) whenever possible.
-- [ ] Verify that the license tags all refer to the _new_ organisation and no longer to Squizlabs. (easily overlooked in new files)
+- [ ] Verify, and if necessary, update the version constraints for dependencies in the `composer.json`.
+- [ ] Verify that any new functions have type declarations whenever possible.
+- [ ] Verify that the license tags all refer to the _new_ organisation and no longer to Squizlabs.
 - [ ] Verify that `@copyright` tags in new files use `@copyright 20xx PHPCSStandards and contributors`.
 - [ ] Check if the GPG key is still valid (not expired).
     If it has expired, create a new key before starting the release process.
@@ -27,13 +29,17 @@
 - [ ] Verify that any new sniffs which have `public` properties are listed on the Customizable Properties page in the Wiki.
 - [ ] Verify that any new CLI options are listed in the Wiki.
 - [ ] Verify that any new Reports have a section in the Reports page in the Wiki.
+- [ ] Whenever relevant, but definitely for a new major, update the output examples which cannot currently be automatically updated.
+    Search for "Regenerate the below output snippet by running the following command" comments to find the relevant sections in the wiki.
 
 ### Majors only
 
-- [ ] Move old changelog entries to `CHANGELOG_OLD.md` file.
 - [ ] Verify that everything deprecated during the previous major was removed.
-- [ ] Update the wiki for any references to anything deprecated/removed.
-- [ ] Change `Config::STABILITY` from "dev" to "stable" for the branch for the new major. - PR #xxx
+- Submit PRs to the documentation repository to update the wiki/website:
+    - [ ] Remove notes from the wiki which refer to features removed in the _previous_ major.
+        I.e. When releasing 4.0, notes about features removed/changed in or before 3.0 can be removed.
+    - [ ] Update sections related to anything deprecated/removed features to mention the deprecation/removal.
+- [ ] Change `Config::STABILITY` from "dev" to "stable" for the branch for the new major.
 
 ### Prepare changelog
 
@@ -76,9 +82,9 @@ Please consider [funding the PHP_CodeSniffer project](https://opencollective.com
 ## Release
 
 - [ ] Merge the changelog PR.
-    For now, cherrypick the changelog to the 4.0 branch.
 - [ ] Make sure all CI builds for the release branch are green.
 - [ ] Create a tag for the release & push it.
+- [ ] Merge any open PRs in the documentation repository which relate to the current release.
 - [ ] Make sure all CI builds are green.
 - [ ] Download the PHAR files from the GH Actions test build page.
 - [ ] Sign the PHAR files using:
@@ -110,7 +116,7 @@ Please consider [funding the PHP_CodeSniffer project](https://opencollective.com
     gh attestation verify phars/phpcbf-x.x.x.phar -o PHPCSStandards
     ```
     - [ ] Commit & push the changes.
-    - [ ] Verify that the website regenerated correctly and that the phars can be downloaded.
+    - [ ] Verify that the [website](https://phars.phpcodesniffer.com/) regenerated correctly.
 - [ ] Create a release & copy & paste the changelog to it.
     - [ ] Upload the unversioned PHAR files + asc files to the release.
     - [ ] Announce the release in the discussions forum by checking the checkbox at the bottom of the release page.