Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update release instructions to include proper branching strategy and protect release branches #221

Merged
merged 3 commits into from Mar 14, 2022
Merged

Update release instructions to include proper branching strategy and protect release branches #221

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
01bd554
Update release instructions to include branching off strategy and all…
felixarntz Mar 8, 2022
2e1684d
Clarify instructions to update trunk branch after release.
felixarntz Mar 8, 2022
d51bdb0
Revise wording based on CR feedback.
felixarntz Mar 9, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
62 changes: 51 additions & 11 deletions docs/Releasing-the-plugin.md
View file
Open in desktop
Expand Up @@ -4,17 +4,32 @@

This document describes the steps to release the Performance plugin.

## Branching off `trunk`

The cutoff point for a release specifies the point in time where no new features or enhancements should go into the release, only critical fixes. There is no hard rule for when this point should be reached, but the loose guidance is around a week before the tentative release date.

### Create a new release branch

At the cutoff time, create a new remote branch `release/{milestoneName}` from latest `trunk`, where `{milestoneName}` is the name of the milestone (which should match the release version). For example, if the milestone is `1.2.0`, name the branch `release/1.2.0`.

### Communicate the change with other contributors

Once the release branch exists, any pull requests that are relevant for that upcoming release need to be based on the release branch instead of `trunk`. For relevant pull requests that are already in progress at the time of creating the branch, change the base branch accordingly.

Most importantly, immediately communicate with the other plugin contributors that the release branch now exists, e.g. by updating the overall release issue with a new comment or leaving a note in the [#performance Slack channel](https://wordpress.slack.com/archives/performance). This way other contributors should be aware that critical pull requests related to that upcoming release need to be based on the release branch instead of `trunk`.

## Preparing the release

### Create a local release branch

Before making any changes, create a local branch `release/{milestoneName}` from latest `trunk`, where `{milestoneName}` is the name of the milestone (which should match the release version). For example, if the milestone is `1.2.0`, name the branch `release/1.2.0`.
Before making any changes, create a new local branch based on the remote release branch `release/{milestoneName}`. Make the following changes in that local branch.

### Update the version number

The version number needs to be updated in the following files:

- package.json
- package-lock.json
- load.php
- readme.txt

Expand All @@ -24,24 +39,49 @@ In addition to those locations, run the `npm run since -- -r {version}` command

The module headers from the plugin have to be translated using a separate `module-i18n.php` file which can be automatically generated and updated. Run `npm run translations` to update the file to reflect the latest available modules.

### Update readme.txt
### Update `readme.txt`

Run `npm run readme -- -m "{milestoneName}"` to update the readme.txt file with the release changelog, where `{milestoneName}` is the name of the milestone. For example, if the milestone is `1.2.0`, the command needs to be `npm run readme -- -m "1.2.0"`.
Run `npm run readme -- -m "{milestoneName}"` to update the `readme.txt` file with the release changelog, where `{milestoneName}` is the name of the milestone. For example, if the milestone is `1.2.0`, the command needs to be `npm run readme -- -m "1.2.0"`.

After running the command, check the readme.txt file to ensure the new changelog for the release has been added. Also review its changelog entries for whether they make sense and are understandable.
After running the command, check the `readme.txt` file to ensure the new changelog for the release has been added. Also review its changelog entries for whether they make sense and are understandable. Make sure that no unexpected changelog entries are present.

### Open a pull request

Push your local release branch to the GitHub repository and open a pull request against `trunk`. Make sure to tag at least 2 plugin maintainers to request a review. Once the pull request is approved by at least 2 plugin maintainers, the pull request can be merged.

If this is a major or minor release, please keep the release branch around since that branch can be used to later create patch releases from the same state of the codebase.
Push your local branch to the GitHub repository and open a pull request against the release branch `release/{milestoneName}`. Make sure to tag at least 2 plugin maintainers to request a review, as usual. Once the pull request is approved by at least 2 plugin maintainers, the pull request can be merged.
felixarntz marked this conversation as resolved.
Show resolved Hide resolved

## Publishing the release

Once the above pull request has been merged, let the other maintainers know on [Slack](https://wordpress.slack.com/archives/performance) that no new commits or pull requests must be added to the branch due to the release process. Then, make sure that all GitHub actions successfully pass for the target branch (e.g. [for `trunk`](https://github.com/WordPress/performance/actions?query=branch%3Atrunk)).
### Notify maintainers and review release branch

Once the above pull request has been merged, let the other maintainers know on [Slack](https://wordpress.slack.com/archives/performance) that no new commits or pull requests must be added to the release branch due to the release process. Then, make sure that all [GitHub workflows](https://github.com/WordPress/performance/actions) successfully pass for the release branch.

### Create the release tag

After that, [create a new release tag for the plugin on GitHub](https://github.com/WordPress/performance/releases/new). The release tag should have the same name as the corresponding milestone used earlier, and it should be created from the release branch `release/{milestoneName}`. Finally, add the changelog (it can be found in the `readme.txt` file) to the release description and create the release.

### Review and test the deployment

Once a new version is released on GitHub, the plugin will be deployed to the [WordPress.org repository](https://wordpress.org/plugins/performance-lab/). [The deployment workflow progress can be tracked here.](https://github.com/WordPress/performance/actions/workflows/deploy-dotorg.yml)

At this point, test the update process from your WordPress site, getting the plugin from wordpress.org. The main aspects to test at this point are:

* Install or update the plugin via wordpress.org, ZIP upload, WP-CLI, etc.
* Test the plugin on different WordPress core versions supported.
dainemawer marked this conversation as resolved.
Show resolved Hide resolved
* Test the plugin on a multisite environment as well.
dainemawer marked this conversation as resolved.
Show resolved Hide resolved
* Make sure there are no PHP errors or warnings and that the high-level functionality works.

After successful testing, inform the other maintainers on [Slack](https://wordpress.slack.com/archives/performance) that the new release has been published and that committing may continue.

## Wrapping up the release

### Update `trunk`

Since the release branch was branched off the main branch `trunk`, the latter now needs to be updated to include any additional changes made to the release branch since.

To do that, open a pull request from the release branch to `trunk` (can be done via GitHub UI) and ask two maintainers to approve it. The code in this pull request does not need to be closely reviewed since it was already approved prior, so this is mostly a formal approval.

After that, [create a new release tag for the plugin on GitHub](https://github.com/WordPress/performance/releases/new). The release tag should have the same name as the corresponding milestone used earlier, and it should be created from the `trunk` branch (unless this is for a patch release, in which case it should be created from the corresponding `release/...` branch). Finally, add the changelog (it can be found in the readme.txt file) to the release description and create the release.
### Close the release

Once a new version is released on GitHub, the plugin will be deployed to the [WordPress.org repository](https://wordpress.org/plugins/performance-lab/) using [this action](../.github/workflows/deploy-dotorg.yml).
As a last action, close the [GitHub milestone](https://github.com/WordPress/performance/milestones) for the release. Make sure that all issues in the milestone are closed.

At this point, test the update process from your WordPress site, getting the plugin from wordpress.org. You can then share on [Slack](https://wordpress.slack.com/archives/performance) that the new release has been published and that committing may continue.
**Don't delete the release branch** since that branch can be used to later create patch releases from the same state of the codebase.