Update release documentation

Author: alcaeus

CONTRIBUTING.md

@@ -296,18 +296,27 @@ generation script.
 
 ## Releasing
 
-The following steps outline the release process for both new minor versions (e.g.
-releasing the `master` branch as X.Y.0) and patch versions (e.g. releasing the
-`vX.Y` branch as X.Y.Z).
+### Branch management
 
-The command examples below assume that the canonical "mongodb" repository has
-the remote name "mongodb". You may need to adjust these commands if you've given
-the remote another name (e.g. "upstream"). The "origin" remote name was not used
-as it likely refers to your personal fork.
+When releasing a new minor version of the driver (i.e. `vX.Y.0`), create a new
+maintenance branch named `vX.Y` from the default branch. Then, update the 
+version information in the default branch to the next minor release:
 
-It helps to keep your own fork in sync with the "mongodb" repository (i.e. any
-branches and tags on the main repository should also exist in your fork). This
-is left as an exercise to the reader.
+```shell
+$ ./bin/update-release-version.php minor
+```
+
+Commit and push the resulting changes:
+
+```shell
+$ git commit -m "Master is now X.Y-dev" phongo_version.h
+$ git push mongodb
+```
+
+Before starting the release process, make sure that all open merge-up pull
+requests containing changes from the release branch have been merged. Handling
+the merge conflicts resulting from the version updates will be much more
+difficult if other changes need merging.
 
 ### Transition JIRA issues and version
 
@@ -323,7 +332,64 @@ Update the version's release date and status from the
 [Manage Versions](https://jira.mongodb.org/plugins/servlet/project-config/PHPC/versions)
 page.
 
-### Update version info
+### Trigger the release workflow
+
+Releases are done automatically through a GitHub Action. Visit the corresponding
+[Release New Version](https://github.com/mongodb/mongo-php-driver/actions/workflows/release.yml)
+workflow page to trigger a new build. Select the correct branch (e.g. `v1.18`)
+and trigger a new run using the "Run workflow" button. In the following prompt,
+enter the version number and the corresponding JIRA release number for the 
+release. This will create and push the necessary commits and tag, create a draft
+release, and trigger the packaging builds for the newly created tag. The release
+is created in a draft state and can be published once the release notes have 
+been updated.
+
+### Upload package to PECL
+
+Once the packaging workflow has finished creating the PECL package, it will be
+published as a build artifact of the package workflow, as well as a release
+artifact in the draft release. This package may be published via the
+[Release Upload](https://pecl.php.net/release-upload.php) form. You will have
+one chance to confirm the package information after uploading.
+
+> **Note:** If downloading the package from the build artifacts, be aware that
+> these are always provided as zip files. You'll have to unpack the tgz archive
+> prior to uploading it to PECL.
+
+### Update compatibility tables in MongoDB docs
+
+For minor releases, create a DOCSP ticket indicating whether there are changes
+to MongoDB Server or PHP version compatibility. The [compatibility tables](https://docs.mongodb.com/drivers/driver-compatibility-reference#php-driver-compatibility)
+in the MongoDB documentation must be updated to account for new releases. Make
+sure to update both MongoDB and Language compatibility tables, as shown in
+[this pull request](https://github.com/mongodb/docs-ecosystem/pull/642).
+
+### Handle merge-up pull request
+
+After the release automation pushes changes to the stable branch the release was
+created from, the merge automation will create a new pull request to merge these
+changes into the next versioned branch. Since version changes always create a
+conflict, follow the "Ignoring Changes" section in the pull request to resolve
+the conflicts and merge the pull request once the build completes.
+
+### Manual release process
+
+The following steps outline the manual release process for both new minor
+versions (e.g. releasing the `master` branch as X.Y.0) and patch versions (e.g.
+releasing the `vX.Y` branch as X.Y.Z). These are preserved for historical 
+reasons and cases that are currently not supported by the release automation 
+(e.g. beta releases).
+
+The command examples below assume that the canonical "mongodb" repository has
+the remote name "mongodb". You may need to adjust these commands if you've given
+the remote another name (e.g. "upstream"). The "origin" remote name was not used
+as it likely refers to your personal fork.
+
+It helps to keep your own fork in sync with the "mongodb" repository (i.e. any
+branches and tags on the main repository should also exist in your fork). This
+is left as an exercise to the reader.
+
+#### Update version info
 
 The PHP driver uses [semantic versioning](http://semver.org/). Do not break
 backwards compatibility in a non-major release or your users will kill you.
@@ -333,17 +399,11 @@ changes in this maintenance branch. This is important because we will later
 merge the ensuing release commits up to master with `--strategy=ours`, which
 will ignore changes from the merged commits.
 
-Update the version and stability constants in `phongo_version.h`. This should
-entail removing the version's "-dev" suffix, changing the stability to
-"stable", and increasing the last digit for `PHP_MONGO_VERSION_DESC`:
+Update the version and stability constants in `phongo_version.h` for the stable
+release:
 
-```diff
--#define PHP_MONGODB_VERSION "1.1.8-dev"
--#define PHP_MONGODB_STABILITY "devel"
--#define PHP_MONGODB_VERSION_DESC 1,1,8,0
-+#define PHP_MONGODB_VERSION "1.1.8"
-+#define PHP_MONGODB_STABILITY "stable"
-+#define PHP_MONGODB_VERSION_DESC 1,1,8,1
+```shell
+$ ./bin/update-release-version.php stable
 ```
 
 The Makefile targets for creating the PECL package depend on these constants, so
@@ -359,7 +419,7 @@ you must rebuild the extension after updating `phongo_version.h`.
 > `PHP_MONGODB_VERSION`, increment the last digit of
 > `PHP_MONGODB_VERSION_DESC`.
 
-### Build PECL package
+#### Build PECL package
 
 Create the PECL package description file with `make package.xml`. This creates
 a `package.xml` file from a template. Version, author, and file information will
@@ -377,32 +437,11 @@ $ pecl install -f mongodb-X.Y.Z.tgz
 Commit the modified `phongo_version.h` file and push this change:
 
 ```
-$ git add phongo_version.h
-$ git commit -m "Package X.Y.Z"
+$ git commit -m "Package X.Y.Z" phongo_version.h
 $ git push mongodb
 ```
 
-> **Note:** Pushing this commit independently from the subsequent "Back to -dev"
-> commit will ensure that Windows build artifacts are created for the release.
-
-### Ensure Windows build artifacts exist
-
-Windows builds are tested by GitHub Actions. Each successful build for a pushed
-commit will produce a build artifact consisting of DLL and PDB files for that
-environment (e.g. 8.0-nts-x64). These build artifacts are later used to create
-release assets (see:
-[windows-release-build.yml](.github/workflows/windows-release-build.yml)).
-
-Before publishing a release in GitHub, ensure that all Windows builds for the
-tag's commit have succeeded and that the necessary build artifacts have been
-created. This can be done by examining the build artifacts in the workflow run
-summary for the "Package X.Y.Z" commit (i.e. tag target).
-
-> **Note:** the "published" event applies to both releases and pre-releases. See
-> [Events that trigger workflows: release](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#release)
-> for more details.
-
-### Tag the release
+#### Tag the release
 
 Create a tag for the release and push:
 
@@ -411,24 +450,22 @@ $ git tag -a -m "Release X.Y.Z" X.Y.Z
 $ git push mongodb --tags
 ```
 
-### Release PECL package
+Pushing the new tag will start the packaging process which provides the PECL 
+and Windows packages that should be attached to the release.
+
+#### Release PECL package
 
 The PECL package may be published via the
 [Release Upload](https://pecl.php.net/release-upload.php) form. You will have
 one chance to confirm the package information after uploading.
 
-### Update version info back to dev
+#### Update version info back to dev
 
 After tagging, the version and stability constants in `phongo_version.h` should
-be updated back to development status.
+be updated back to development status:
 
-```diff
--#define PHP_MONGODB_VERSION "1.1.8"
--#define PHP_MONGODB_STABILITY "stable"
--#define PHP_MONGODB_VERSION_DESC 1,1,8,1
-+#define PHP_MONGODB_VERSION "1.1.9-dev"
-+#define PHP_MONGODB_STABILITY "devel"
-+#define PHP_MONGODB_VERSION_DESC 1,1,9,0
+```shell
+$ ./bin/update-release-version.php patch
 ```
 
 Commit and push this change:
@@ -444,52 +481,7 @@ $ git push mongodb
 > "1.4.0beta1" and "beta" for the first beta release, this step would see them
 > ultimately changed to "1.4.0beta2-dev" and "devel".
 
-### Branch management
-
-#### After releasing a new minor version
-
-After a new minor version is released (i.e. `master` was tagged), a maintenance
-branch should be created for future patch releases:
-
-```
-$ git checkout -b vX.Y
-$ git push mongodb vX.Y
-```
-
-Update `phongo_version.h` for the `master` branch:
-
-```diff
--#define PHP_MONGODB_VERSION "1.15.1-dev"
-+#define PHP_MONGODB_VERSION "1.16.0-dev"
- #define PHP_MONGODB_STABILITY "devel"
--#define PHP_MONGODB_VERSION_DESC 1,15,1,0
-+#define PHP_MONGODB_VERSION_DESC 1,16,0,0
-```
-
-Commit and push this change:
-
-```
-$ git commit -m "Master is now X.Y-dev" phongo_version.h
-$ git push mongodb
-```
-
-#### After releasing a patch version
-
-If this was a patch release, the maintenance branch must be merged up to master:
-
-```
-$ git checkout master
-$ git pull mongodb master
-$ git merge vX.Y --strategy=ours
-$ git push mongodb
-```
-
-The `--strategy=ours` option ensures that all changes from the merged commits
-will be ignored. This is OK because we previously ensured that the `master`
-branch was up-to-date with all code changes in this maintenance branch before
-tagging.
-
-### Publish release notes
+#### Publish release notes
 
 The following template should be used for creating GitHub release notes via
 [this form](https://github.com/mongodb/mongo-php-driver/releases/new). The PECL
@@ -543,10 +535,3 @@ Thanks for our community contributors for X.Y.Z:
 
 Significant release announcements should also be posted in the
 [MongoDB Product & Driver Announcements: Driver Releases](https://www.mongodb.com/community/forums/tags/c/announcements/driver-releases/110/php) forum.
-
-### Update compatibility tables in MongoDB docs
-
-For minor releases, create a DOCSP ticket indicating whether there are changes to MongoDB Server or PHP version
-compatibility. The [compatibility tables](https://docs.mongodb.com/drivers/driver-compatibility-reference#php-driver-compatibility)
-in the MongoDB documentation must be updated to account for new releases. Make sure to update both MongoDB and Language
-compatibility tables, as shown in [this pull request](https://github.com/mongodb/docs-ecosystem/pull/642).