diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7e9e46404..b54dab2fd 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 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 new file mode 100644 index 000000000..61424a35e --- /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.