diff --git a/docs/assets/Cherry-Pick-Backport-to-GB-RC.png b/docs/assets/Cherry-Pick-Backport-to-GB-RC.png new file mode 100644 index 00000000000000..b7dca4c9d7160a Binary files /dev/null and b/docs/assets/Cherry-Pick-Backport-to-GB-RC.png differ diff --git a/docs/contributors/code/release.md b/docs/contributors/code/release.md index 3dd8863859e37f..eb5d233ec9d92c 100644 --- a/docs/contributors/code/release.md +++ b/docs/contributors/code/release.md @@ -1,6 +1,6 @@ # Gutenberg Release Process -This Repository is used to perform several types of releases. This document serves as a checklist for each one of these. It is helpful if you'd like to understand the different workflows. +This repository is used to perform several types of releases.It is helpful if you'd like to understand the different workflows. To release a stable version of the Gutenberg plugin you need: - To be part of the [Gutenberg development team](/docs/block-editor/contributors/repository-management/#teams), to launch the GitHub actions related to the release process and to potentially backport PRs to the release branch. @@ -11,29 +11,62 @@ To [release WordPress's npm packages](#packages-releases-to-npm-and-wordpress-co ## Plugin Releases + +The first step is [creating an issue in the Gutenberg repo](https://github.com/WordPress/gutenberg/issues/new?assignees=&labels=&projects=&template=New_release.md). +The issue template is called: "Gutenberg Release" and contains a checklist for the complete release process from Release Candidate to changelog curation to cherry-picking, stable release to release post. +The [issue for Gutenberg 15.7](https://github.com/WordPress/gutenberg/issues/50092) is a good example. + +The checklist helps you coordinate with the developer and other teams. + +The Schedule will help you fill in the blank on the top of the issue. + ### Schedule We release a new major version approximately every two weeks. The current and next versions are [tracked in GitHub milestones](https://github.com/WordPress/gutenberg/milestones), along with each version's tagging date (the day when _the release candidate_ is to be tagged). -- **On the date of the current milestone**, we publish a release candidate and make it available for plugin authors and users to test. If any regressions are found with a release candidate, a new one can be published. On this date, all remaining PRs on the milestone are moved automatically to the next release. Release candidates should be versioned incrementally, starting with `-rc.1`, then `-rc.2`, and so on. [Preparation of the release post starts here](/docs/block-editor/contributors/code/release/#writing-the-release-notes-and-post) and spans until the final release. +- **On the date of the current milestone**, we publish a release candidate and make it available for plugin authors and users to test. If any regressions are found with a release candidate, a new one can be published. On this date, all remaining PRs on the milestone are moved automatically to the next release. + +Release candidates should be versioned incrementally, starting with `-rc.1`, then `-rc.2`, and so on. [Preparation of the release post starts here](/docs/block-editor/contributors/code/release/#writing-the-release-notes-and-post) and spans until the final release. - **One week after the first release candidate**, the stable version is created based on the last release candidate and any necessary regression fixes. Once the stable version is released and the release post is published. If critical bugs are discovered on stable versions of the plugin, patch versions can be released at any time. +When it's time, announce in core-editor channel that you are about to start the RC workflow. + +### Organize and Label PRs on the relevant milestone +An example of such a review was published with 15.8 release, including the label changes made. + +The changelog automation can be called separately from the release workflow with the following command on your local copy: + +```npm run other:changelog -- --milestone="Gutenberg 15.8"``` +With the milestone being the final release version as string. + +The output of this command is the changelog for this milestone at this moment time. Copy/paste it into a Markdown document so you can view it and follow the links to the PRs. + +The three sections to review are +- Enhancements - look for PRs that don’t have any sub category attached +- Bug fixes - also look for PRs that don’t have any sub-category attached, +- Various - that is created with PRs that don’t have any labels at all. + +Changing the labels on PRs is much faster then reorganizing an existing changelog in the release section afterwards. + +Now you are ready to start the release candidate worklow. + ### Release Tool -The plugin release process is entirely automated and happens solely on GitHub -- i.e. it doesn't require any steps to be run locally on your machine. +The plugin release process is mostly automated and happens solely on GitHub -- i.e. it doesn't require any steps to be run locally on your machine. For your convenience, here's an [11-minute video walkthrough](https://youtu.be/TnSgJd3zpJY) that demonstrates the release process. It's recommended to watch this if you're unfamiliar with it. The process is also documented in the following paragraphs. #### Running workflow -In order to start the release process, go to Gutenberg's GitHub repository's Actions tab, and locate the ["Build Gutenberg Plugin Zip" action](https://github.com/WordPress/gutenberg/actions/workflows/build-plugin-zip.yml). Note the blue banner that says "This workflow has a `workflow_dispatch` event trigger.", and expand the "Run workflow" dropdown on its right hand side. +To start the release process, go to Gutenberg's GitHub repository's Actions tab, and locate the ["Build Gutenberg Plugin Zip" action](https://github.com/WordPress/gutenberg/actions/workflows/build-plugin-zip.yml). Note the blue banner that says "This workflow has a `workflow_dispatch` event trigger.", and expand the "Run workflow" dropdown on its right hand side. ![Run workflow dropdown for the plugin release](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/contributors/code/workflow-dispatch-plugin-banner.png) -To release a release candidate (RC) version of the plugin, enter `rc`. To release a stable version, enter `stable`. In each case, press the green "Run workflow" button. +To release a release candidate (RC) version of the plugin, enter `rc`. +To release a stable version, enter `stable`. In each case, press the button **Run workflow** This will trigger a GitHub Actions (GHA) workflow that bumps the plugin version, builds the Gutenberg plugin .zip file, creates a release draft, and attaches the plugin .zip file to it. This part of the process typically takes a little under six minutes. You'll see that workflow appear at the top of the list, right under the blue banner. Once it's finished, it'll change its status icon from a yellow dot to a green checkmark. You can follow along in a more detailed view by clicking on the workflow. @@ -47,16 +80,34 @@ This message is misleading and no action is required by the release coordinator. As soon as the workflow has finished, you'll find the release draft under [Gutenberg Releases](https://github.com/WordPress/gutenberg/releases). The draft is pre-populated with changelog entries based on previous release candidates for this version and any changes that have since been cherry-picked to the release branch. Thus, when releasing the first stable version of a series, delete any RC version headers (that are only there for your information) and move the more recent changes to the correct section (see below). -The changelog draft will be partially pre-organized (based on GitHub labels) into sections and, within those, into “features.” Take some time to read the generated notes and then edit them to ensure legibility and accuracy. +## Streamline curating the release changelog. + +The best time to work on the Changelog is at the moment when it’s first created during the Release candidate workflow. That’s when the changelog automation is called and the first version of the Changelog is available in the Release. + +The stable release process takes the RC candidates changelogs and adds them to the stable release. There is one caveat: The stable release only ‘remembers’ the first version, that is the version that is available when the Release candidate releases is published. Subsequent changes of the changelog of release candidates won’t make it into the stable release; only the first version. + +That means if you curate the whole changelog before you publish the Release candidate, you won’t have to work on it for the stable release, except for the few items of subsequent RC 2 or 3 releases that will also be added to the stable release. + +The changelog process is mostly automated, it however depends heavily on proper labeling of the PRs. Before you run the RC candidate, you can save yourself additional time by checking that all PRs have proper labeling. + +One the release changelog is available on draft, make some time to read the generated notes and then edit them to ensure legibility and accuracy. Don't rush this part. It's important to ensure the release notes are as organized as possible, and it doesn't need to be completed in one go. You can save the draft and come back to it later. -When editing the notes, you should be sure to: +If you are worried that people couldn’t get access to the release candidate version until you publish the release: you can share the release artifact with the core-editor channel as it was already created, and you buy yourself some time to finish the changelog curation task. + +### Guidelines for proof-reading changelog items +- Move all entries under the Various section to a more appropriate section. +- Fix spelling errors or clarify wording. Phrasing should be easy to understand where the intended audience is those who use the plugin or are keeping up with ongoing development. +- Create new groupings as applicable, and move pull requests between. +- When multiple pull requests relate to the same task (such as a follow-up pull request), try to combine them to a single entry. Good examples for this are PRs around removing Lodash for performance purposes, replacement of Puppeteer E2D tests with Playwright or efforts to convert public components to TypeScript. +- If subtasks of a related set of pull requests are substantial, consider organizing as entries in a nested list. +- If one or more pull requests revert one or more pull requests in the same release netting a zero-sum of code changes, remove them. +- Remove all mobile app pull request entries (the only exception to this rule is if the mobile PR also updates functionality for the web). +- If subheaders only have one item listed, remove the subheader and move the PR to the next matching subheader that has more than one item listed. -1. Delete the `Various` section and move anything under it to a more appropriate section. -2. Move all features under `Uncategorized` bullet points to a more suitable feature. +As mentioned, the stable release process pulls from the first published changelogs from each release candidate. Edit the changelog before you publish the release. -You can find some more tips on writing the release notes and post in the section below. #### Creating Release Candidate Patches @@ -67,10 +118,32 @@ There are a couple of ways a release coordinator might be made aware of these bu - Contributors may add the `Backport to Gutenberg RC` label to a closed PR. [Do a search for any of these PRs](https://github.com/WordPress/gutenberg/pulls?q=is%3Apr+label%3A%22Backport+to+Gutenberg+RC%22+is%3Aclosed) before publishing the final release. - You may receive a direct message or a ping in the #core-editor channel in slack notifying you of PRs that need to be included in the release candidate. Even when this is the case, the `Backport to Gutenberg RC` should be added to the PR. -The cherry-picking process is handled as follows: + +The cherry-picking process can be automated with the [`npm run cherry-pick` script](/docs/contributors/code/auto-cherry-picking.md), but make sure to use the `Backport to Gutenberg RC` label when running the command. + +_Switch to the release branch_ + +```git checkout release/X.Y``` + +_Cherry-pick all the merged PRs with a relevant backport label_ + +```npm run other:cherry-pick "Backport to Gutenberg RC"``` + +The script +- cherry-picks all PRs with the label 'Backport to Gutenberg RC' +- Adds them to the release milestone, +- git push all changes to the release branch +- Adds a comment to the PR and +- once done, it also removes the label 'Backport to Gutenber RC' from the PR. + +Here is a screenshot of the process: +![](/docs/assets/Cherry-Pick-Backport-to-GB-RC.png) + + +If you need to handle cherry-picking one at a time and one step at a time you can follow this sequence manually. 1. Checkout the corresponding release branch with: `git checkout release/x.x`. -2. Cherry-pick fix commits (in chronological order) with `git cherry-pick [SHA]`. The cherry-picking process can be automated with the [`npm run cherry-pick` script](/docs/contributors/code/auto-cherry-picking.md), but make sure to use the `Backport to Gutenberg RC` label when running the command. +2. Cherry-pick fix commits (in chronological order) with `git cherry-pick [SHA]`. 3. When done, push the changes to GitHub: `git push`.
@@ -94,43 +167,27 @@ Once approved, the new Gutenberg version will be available to WordPress users al Once released, all that's left to do is writing a release post on [make.wordpress.org/core](https://make.wordpress.org/core/). You can find some tips on that below. -### Documenting the release with the Release Notes and Post +### Documenting the release with the Release Post
Documenting the release is a group effort between the release manager, Gutenberg core team developers, and designers , comprised of a series of sequential steps that, because of the amount of people involved and the coordination required, need to adhere to a timeline between the RC and stable releases. The release manager will get pinged by a core member to kick-off and coordinate this process.
-1. Curating the changelog - Wednesday after the RC release to Friday -2. Selecting the release highlights - Friday to Monday +1. Selecting the release highlights - Friday to Monday +2. Requesting Release assets via Design team 3. Drafting the release post - Monday to Wednesday 4. Publishing the post - Wednesday after stable release -#### 1. Curating the changelog - -The release notes draft is auto-generated by a script that looks for pull requests for the current milestone, and: - -1. Groups them into sections (by pull request label). -2. Sub-groups them into "features" within each section (again by pull request label) -This is intended to be a starting point for release notes, and manually reviewing and curating the changelog entries is still required. The release candidate changelog is reused in the stable release and greatly helps select the highlights; because depending on the release it can be a very time-consuming process, **it is recommended to start this process as soon as the milestone is closed** and the release candidate is published. - -Guidelines for proof-reading include: - -- Move _all_ entries under the `Various` section to a more appropriate section. -- Move _all_ features listed under the `Uncategorized` bullet points to a more suitable feature grouping. -- Fix spelling errors or clarify wording. Phrasing should be easy to understand where the intended audience is those who use the plugin or are keeping up with ongoing development. -- Create new groupings as applicable, and move pull requests between. -- When multiple pull requests relate to the same task (such as a follow-up pull request), try to combine them to a single entry. -- If subtasks of a related set of pull requests are substantial, consider organizing as entries in a nested list. -- If one or more pull requests revert one or more pull requests in the same release netting a zero-sum of code changes, remove them. -- Remove all mobile app pull request entries (the only exception to this rule is if the mobile PR also updates functionality for the web). - -#### 2. Selecting the release highlights +#### 1. Selecting the release highlights Once the changelog is cleaned up, the next step is to choose a few changes to highlight in the release post. These highlights usually focus on new features and enhancements, including performance and accessibility ones, but can also include important API changes or critical bug fixes. Given the big scope of Gutenberg and the high number of pull requests merged in each milestone, it is not uncommon to overlook impactful changes worth highlighting; because of this, this step is a collaborative effort between the release manager, design, and Gutenberg Core team members. +#### 2. Requesting release assets from design team +Once the highlights are identified, the release lead request visual assets for the main highlights from the design team via a post in the WordPress #design channel. The assets will be providedd via the Google Drive folder for the specific release. + #### 3. Drafting the release post Because of the nature of the release post content, responsibilities are divided in this step. While the post **can either be drafted by the release manager or delegated to another core member** agreed upon in advance, **visual assets are created by the design team**. @@ -139,7 +196,7 @@ When possible, the highlighted changes in the release post should include an ani These visual assets should maintain consistency with previous release posts; using lean, white themes helps in this regard and visually integrate well with the [make.wordpress.org/core](https://make.wordpress.org/core/) blog aesthetics. Including copyrighted material should be avoided, and browser plugins that can be seen in the browser canvas (spell checkers, form fillers, etc.) disabled when capturing the assets. -#### 5. Publishing the post +#### 4. Publishing the post Once the post content is ready, an author already having permissions to post in [make.wordpress.org/core](https://make.wordpress.org/core/) will create a new draft and import the content; this post should be published after the actual release, helping external media to echo and amplify the release news. Remember asking for peer review is encouraged by the [make/core posting guidelines](https://make.wordpress.org/core/handbook/best-practices/post-comment-guidelines/#peer-review)!