From 9798946a6eb7ae54f1e6454e1e34bcdd1c61f66a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Thu, 22 Jun 2023 13:39:28 +0200 Subject: [PATCH 1/2] Extract realeasing process from contributing doc --- CONTRIBUTING.md | 231 +---------------------------------------------- RELEASING.md | 232 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 234 insertions(+), 229 deletions(-) create mode 100644 RELEASING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7e9e46404..0143dc862 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -190,234 +190,7 @@ repository: informational log messages with the `--level warning` option. * Generated documentation may be found in the `build/master/html` directory. -## Creating a maintenance branch and updating master branch alias - -After releasing a new major or minor version (e.g. 1.9.0), a maintenance branch -(e.g. v1.9) should be created. Any development towards a patch release (e.g. -1.9.1) would then be done within that branch and any development for the next -major or minor release can continue in master. - -After creating a maintenance branch, the `extra.branch-alias.dev-master` field -in the master branch's `composer.json` file should be updated. For example, -after branching v1.9, `composer.json` in the master branch may still read: - -``` -"branch-alias": { - "dev-master": "1.9.x-dev" -} -``` - -The above would be changed to: - -``` -"branch-alias": { - "dev-master": "1.10.x-dev" -} -``` - -Commit this change: - -``` -$ git commit -m "Master is now 1.10-dev" composer.json -``` - ## 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). - -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. - -### Ensure PHP version compatibility - -Ensure that the library test suite completes on supported versions of PHP. - -### Transition JIRA issues and version - -All issues associated with the release version should be in the "Closed" state -and have a resolution of "Fixed". Issues with other resolutions (e.g. -"Duplicate", "Works as Designed") should be removed from the release version so -that they do not appear in the release notes. - -Check the corresponding ".x" fix version to see if it contains any issues that -are resolved as "Fixed" and should be included in this release version. - -Update the version's release date and status from the -[Manage Versions](https://jira.mongodb.org/plugins/servlet/project-config/PHPLIB/versions) -page. - -### Update version info - -The PHP library uses [semantic versioning](https://semver.org/). Do not break -backwards compatibility in a non-major release or your users will kill you. - -Before proceeding, ensure that the `master` branch is up-to-date with all code -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 composer.json and CI matrices - -This is especially important before releasing a new minor version. - -Ensure that the extension requirement and branch alias in `composer.json` are -correct for the library version being released. For example, the 1.15.0 release -of the library should depend on version `^1.15.0` of the extension and master -branch alias should be `1.15.x-dev`. - -If this is the first release of a minor version for the library, it is likely -following an extension release. In that case, the `driver-versions` matrix in -the Evergreen configuration should be updated: - -```diff - - id: "oldest-supported" -- display_name: "PHPC 1.15-dev" -+ display_name: "PHPC 1.15.0" - variables: -- EXTENSION_BRANCH: "master" -+ EXTENSION_VERSION: "1.15.0" - - id: "latest-stable" -- display_name: "PHPC 1.15-dev" -+ display_name: "PHPC 1.15.x" - variables: -- EXTENSION_BRANCH: "master" -+ EXTENSION_VERSION: "stable" - - id: "latest-dev" -- display_name: "PHPC 1.15-dev" -+ display_name: "PHPC 1.16-dev" - variables: - EXTENSION_BRANCH: "master" -``` - -Commit and push any changes: - -``` -$ git commit -m "Update composer.json and CI matrices for X.Y.Z" composer.json .evergreen/config.yml -$ git push mongodb -``` - -### Tag the release - -Create a tag for the release and push: - -``` -$ git tag -a -m "Release X.Y.Z" X.Y.Z -$ git push mongodb --tags -``` - -### 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 the master branch alias in `composer.json`: - -```diff - "extra": { - "branch-alias": { -- "dev-master": "1.15.x-dev" -+ "dev-master": "1.16.x-dev" - } - }, -``` - -Commit and push this change: - -``` -$ git commit -m "Master is now X.Y-dev" composer.json -$ 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 - -The following template should be used for creating GitHub release notes via -[this form](https://github.com/mongodb/mongo-php-library/releases/new). - -```markdown -The PHP team is happy to announce that version X.Y.Z of the MongoDB PHP library is now available. - -**Release Highlights** - - - -A complete list of resolved issues in this release may be found in [JIRA]($JIRA_URL). - -**Documentation** - -Documentation for this library may be found in the [PHP Library Manual](https://mongodb.com/docs/php-library/current/). - -**Installation** - -This library may be installed or upgraded with: - - composer require mongodb/mongodb:X.Y.Z - -Installation instructions for the `mongodb` extension may be found in the [PHP.net documentation](https://php.net/manual/en/mongodb.installation.php). -``` - -The URL for the list of resolved JIRA issues will need to be updated with each -release. You may obtain the list from -[this form](https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=12483). - -If commits from community contributors were included in this release, append the -following section: - -```markdown -**Thanks** - -Thanks for our community contributors for this release: - - * [$CONTRIBUTOR_NAME](https://github.com/$GITHUB_USERNAME) -``` - -Release announcements should also be posted in the [MongoDB Product & Driver Announcements: Driver Releases](https://mongodb.com/community/forums/tags/c/announcements/driver-releases/110/php) forum and shared on Twitter. - -### Documentation Updates for New Major and Minor Versions - -New major and minor releases will also require documentation updates to other -projects: - - * Create a DOCSP ticket to add the new version to PHP's server and language - [compatibility tables](https://mongodb.com/docs/drivers/php/#compatibility) - in the driver docs portal. See - [mongodb/docs-ecosystem#642](https://github.com/mongodb/docs-ecosystem/pull/642) - for an example. - - * Create a DOCSP ticket to update the "current" and "upcoming" navigation links - in the library's [documentation](https://mongodb.com/docs/php-library/current). This - will require updating - [mongodb/docs-php-library](https://github.com/mongodb/docs-php-library). - -These tasks can be initiated prior to tagging a new release to ensure that the -updated content becomes accessible soon after the release is published. +The release are created by the maintainers of the library. The process is documented in +the [RELEASING.md](RELEASING.md) file. diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 000000000..10fabdaf9 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,232 @@ +## 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). + +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. + +### Ensure PHP version compatibility + +Ensure that the library test suite completes on supported versions of PHP. + +### Transition JIRA issues and version + +All issues associated with the release version should be in the "Closed" state +and have a resolution of "Fixed". Issues with other resolutions (e.g. +"Duplicate", "Works as Designed") should be removed from the release version so +that they do not appear in the release notes. + +Check the corresponding ".x" fix version to see if it contains any issues that +are resolved as "Fixed" and should be included in this release version. + +Update the version's release date and status from the +[Manage Versions](https://jira.mongodb.org/plugins/servlet/project-config/PHPLIB/versions) +page. + +### Update version info + +The PHP library uses [semantic versioning](https://semver.org/). Do not break +backwards compatibility in a non-major release or your users will kill you. + +Before proceeding, ensure that the `master` branch is up-to-date with all code +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 composer.json and CI matrices + +This is especially important before releasing a new minor version. + +Ensure that the extension requirement and branch alias in `composer.json` are +correct for the library version being released. For example, the 1.15.0 release +of the library should depend on version `^1.15.0` of the extension and master +branch alias should be `1.15.x-dev`. + +If this is the first release of a minor version for the library, it is likely +following an extension release. In that case, the `driver-versions` matrix in +the Evergreen configuration should be updated: + +```diff + - id: "oldest-supported" +- display_name: "PHPC 1.15-dev" ++ display_name: "PHPC 1.15.0" + variables: +- EXTENSION_BRANCH: "master" ++ EXTENSION_VERSION: "1.15.0" + - id: "latest-stable" +- display_name: "PHPC 1.15-dev" ++ display_name: "PHPC 1.15.x" + variables: +- EXTENSION_BRANCH: "master" ++ EXTENSION_VERSION: "stable" + - id: "latest-dev" +- display_name: "PHPC 1.15-dev" ++ display_name: "PHPC 1.16-dev" + variables: + EXTENSION_BRANCH: "master" +``` + +Commit and push any changes: + +``` +$ git commit -m "Update composer.json and CI matrices for X.Y.Z" composer.json .evergreen/config.yml +$ git push mongodb +``` + +### Tag the release + +Create a tag for the release and push: + +``` +$ git tag -a -m "Release X.Y.Z" X.Y.Z +$ git push mongodb --tags +``` + +### Branch management + +## Creating a maintenance branch and updating master branch alias + +After releasing a new major or minor version (e.g. 1.9.0), a maintenance branch +(e.g. v1.9) should be created. Any development towards a patch release (e.g. +1.9.1) would then be done within that branch and any development for the next +major or minor release can continue in master. + +After creating a maintenance branch, the `extra.branch-alias.dev-master` field +in the master branch's `composer.json` file should be updated. For example, +after branching v1.9, `composer.json` in the master branch may still read: + +``` +"branch-alias": { + "dev-master": "1.9.x-dev" +} +``` + +The above would be changed to: + +``` +"branch-alias": { + "dev-master": "1.10.x-dev" +} +``` + +Commit this change: + +``` +$ git commit -m "Master is now 1.10-dev" composer.json +``` + +#### 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 the master branch alias in `composer.json`: + +```diff + "extra": { + "branch-alias": { +- "dev-master": "1.15.x-dev" ++ "dev-master": "1.16.x-dev" + } + }, +``` + +Commit and push this change: + +``` +$ git commit -m "Master is now X.Y-dev" composer.json +$ 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 + +The following template should be used for creating GitHub release notes via +[this form](https://github.com/mongodb/mongo-php-library/releases/new). + +```markdown +The PHP team is happy to announce that version X.Y.Z of the MongoDB PHP library is now available. + +**Release Highlights** + + + +A complete list of resolved issues in this release may be found in [JIRA]($JIRA_URL). + +**Documentation** + +Documentation for this library may be found in the [PHP Library Manual](https://mongodb.com/docs/php-library/current/). + +**Installation** + +This library may be installed or upgraded with: + + composer require mongodb/mongodb:X.Y.Z + +Installation instructions for the `mongodb` extension may be found in the [PHP.net documentation](https://php.net/manual/en/mongodb.installation.php). +``` + +The URL for the list of resolved JIRA issues will need to be updated with each +release. You may obtain the list from +[this form](https://jira.mongodb.org/secure/ReleaseNote.jspa?projectId=12483). + +If commits from community contributors were included in this release, append the +following section: + +```markdown +**Thanks** + +Thanks for our community contributors for this release: + + * [$CONTRIBUTOR_NAME](https://github.com/$GITHUB_USERNAME) +``` + +Release announcements should also be posted in the [MongoDB Product & Driver Announcements: Driver Releases](https://mongodb.com/community/forums/tags/c/announcements/driver-releases/110/php) forum and shared on Twitter. + +### Documentation Updates for New Major and Minor Versions + +New major and minor releases will also require documentation updates to other +projects: + + * Create a DOCSP ticket to add the new version to PHP's server and language + [compatibility tables](https://mongodb.com/docs/drivers/php/#compatibility) + in the driver docs portal. See + [mongodb/docs-ecosystem#642](https://github.com/mongodb/docs-ecosystem/pull/642) + for an example. + + * Create a DOCSP ticket to update the "current" and "upcoming" navigation links + in the library's [documentation](https://mongodb.com/docs/php-library/current). This + will require updating + [mongodb/docs-php-library](https://github.com/mongodb/docs-php-library). + +These tasks can be initiated prior to tagging a new release to ensure that the +updated content becomes accessible soon after the release is published. From 36557f69ba2aaf4b694d2bfaca7a77e49dce2708 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= Date: Mon, 26 Jun 2023 10:07:35 +0200 Subject: [PATCH 2/2] Formatting --- CONTRIBUTING.md | 2 +- RELEASING.md | 24 ++++++++++++------------ 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0143dc862..b54dab2fd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -192,5 +192,5 @@ repository: ## Releasing -The release are created by the maintainers of the library. The process is documented in +The releases are created by the maintainers of the library. The process is documented in the [RELEASING.md](RELEASING.md) file. diff --git a/RELEASING.md b/RELEASING.md index 10fabdaf9..61424a35e 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -1,4 +1,4 @@ -## Releasing +# 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 @@ -13,11 +13,11 @@ 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. -### Ensure PHP version compatibility +## Ensure PHP version compatibility Ensure that the library test suite completes on supported versions of PHP. -### Transition JIRA issues and version +## Transition JIRA issues and version All issues associated with the release version should be in the "Closed" state and have a resolution of "Fixed". Issues with other resolutions (e.g. @@ -31,7 +31,7 @@ Update the version's release date and status from the [Manage Versions](https://jira.mongodb.org/plugins/servlet/project-config/PHPLIB/versions) page. -### Update version info +## Update version info The PHP library uses [semantic versioning](https://semver.org/). Do not break backwards compatibility in a non-major release or your users will kill you. @@ -41,7 +41,7 @@ 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 composer.json and CI matrices +## Update composer.json and CI matrices This is especially important before releasing a new minor version. @@ -81,7 +81,7 @@ $ git commit -m "Update composer.json and CI matrices for X.Y.Z" composer.json . $ git push mongodb ``` -### Tag the release +## Tag the release Create a tag for the release and push: @@ -90,9 +90,9 @@ $ git tag -a -m "Release X.Y.Z" X.Y.Z $ git push mongodb --tags ``` -### Branch management +## Branch management -## Creating a maintenance branch and updating master branch alias +# Creating a maintenance branch and updating master branch alias After releasing a new major or minor version (e.g. 1.9.0), a maintenance branch (e.g. v1.9) should be created. Any development towards a patch release (e.g. @@ -123,7 +123,7 @@ Commit this change: $ git commit -m "Master is now 1.10-dev" composer.json ``` -#### After releasing a new minor version +### 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: @@ -151,7 +151,7 @@ $ git commit -m "Master is now X.Y-dev" composer.json $ git push mongodb ``` -#### After releasing a patch version +### After releasing a patch version If this was a patch release, the maintenance branch must be merged up to master: @@ -168,7 +168,7 @@ 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-library/releases/new). @@ -212,7 +212,7 @@ Thanks for our community contributors for this release: Release announcements should also be posted in the [MongoDB Product & Driver Announcements: Driver Releases](https://mongodb.com/community/forums/tags/c/announcements/driver-releases/110/php) forum and shared on Twitter. -### Documentation Updates for New Major and Minor Versions +## Documentation Updates for New Major and Minor Versions New major and minor releases will also require documentation updates to other projects: