From 01dc764a459149c3bb26102cf889bc7b00b331ef Mon Sep 17 00:00:00 2001 From: Dave Smith Date: Tue, 20 Jul 2021 15:37:13 +0100 Subject: [PATCH 1/2] Update docs to reflect new automated process for feature grouping --- docs/contributors/code/release.md | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/docs/contributors/code/release.md b/docs/contributors/code/release.md index d4420e7ad49e8..2cdecf36327bf 100644 --- a/docs/contributors/code/release.md +++ b/docs/contributors/code/release.md @@ -34,7 +34,18 @@ To release a release candidate (RC) version of the plugin, enter `rc`. To releas 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. -As soon as the workflow has finished, you'll find the release draft under 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, make sure to delete any RC version headers (that are only there for your information), and to move the more recent changes to the corresponding sections below. Furthermore, take some time to edit the release notes into a more legible format, by grouping related entries under common bullet points. Don't rush this part -- it's important to bring the release notes into a nice shape. You don't have to do it all in one go -- you can save the draft and come back to it later. You can find some more tips on writing the release notes and post in the section below. +As soon as the workflow has finished, you'll find the release draft under 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, make sure to delete any RC version headers (that are only there for your information) and to move the more recent changes to the correct section (see below). + +The changelog draft will be at least partially pre-organized (based on Github label) into sections and within those into "features". Take 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 bring the release notes into a nice shape. You don't have to do it all in one go -- you can save the draft and come back to it later. + +When editing the notes, you should be sure to: + +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. + +You can find some more tips on writing the release notes and post in the section below. Only once you're happy with the shape of the release notes should you press the green "Publish release" button. This will create a `git` tag for the version, publish the release, and trigger [another GHA workflow](https://github.com/WordPress/gutenberg/actions/workflows/upload-release-to-plugin-repo.yml) that has a twofold purpose: @@ -62,17 +73,23 @@ Documenting the release is a group effort between the release manager, Gutenberg #### 1. Curating the changelog -The release notes draft is auto-generated by a script that looks for pull requests for the current milestone, and groups them by pull request label. +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 mobile app pull request entries. +- Remove all mobile app pull request entries. #### 2. Selecting the release highlights From 0d262825a6af80925fa80fa4f72351583a0b61a5 Mon Sep 17 00:00:00 2001 From: Dave Smith Date: Fri, 30 Jul 2021 09:15:43 +0100 Subject: [PATCH 2/2] Add note about exception for mobile PRs See https://github.com/WordPress/gutenberg/pull/33573#discussion_r679671911 --- docs/contributors/code/release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributors/code/release.md b/docs/contributors/code/release.md index 2cdecf36327bf..51d89f852ffae 100644 --- a/docs/contributors/code/release.md +++ b/docs/contributors/code/release.md @@ -89,7 +89,7 @@ Guidelines for proof-reading include: - 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. +- 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