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.

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

Update docs to reflect new automated process for feature grouping #33573

Merged
merged 2 commits into from
Jul 30, 2021
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 20 additions & 3 deletions docs/contributors/code/release.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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.
getdave marked this conversation as resolved.
Show resolved Hide resolved

#### 2. Selecting the release highlights

Expand Down