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

Handbook: Update Gutenberg release documentation to clarify release post workflow #33328

Merged
merged 9 commits into from
Jul 14, 2021
Merged

Handbook: Update Gutenberg release documentation to clarify release post workflow #33328

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
4335cac
Update release process documentation
priethor Jul 9, 2021
e3e2ab3
Fix typos and formatting.
priethor Jul 9, 2021
cf22f53
Fix formatting.
priethor Jul 9, 2021
e466c4d
Rewording to avoid second person.
priethor Jul 9, 2021
330dd24
Update release.md
priethor Jul 9, 2021
b6916ed
Add a reference to being pinged to coordinate
priethor Jul 9, 2021
cac4953
Update Gutenberg membership requirements.
priethor Jul 9, 2021
93ab896
Fix internal handbook links
priethor Jul 13, 2021
56eb56e
Reword the drafting and publishing, clarify permissions to post on ma…
priethor Jul 13, 2021
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
38 changes: 20 additions & 18 deletions docs/contributors/code/release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

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.

To release a stable version of the Gutenberg plugin, you need approval from a member of the Gutenberg Core team for the final step of the release process (upload to the WordPress.org plugin repo -- see below). If you aren't a member yourself, make sure to contact one ahead of time so they'll be around at the time of the release. You can ping in the [#core-editor Slack channel](https://wordpress.slack.com/messages/C02QB2JS7).
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). On top of that, you need approval from a member of the Gutenberg Core team for the final step of the release process (upload to the WordPress.org plugin repo -- see below). If you aren't a member yourself, make sure to contact one ahead of time so they'll be around at the time of the release. You can ping in the [#core-editor Slack channel](https://wordpress.slack.com/messages/C02QB2JS7).

To release Gutenberg's npm packages, you need to be part of the [WordPress organization at npm](https://www.npmjs.com/org/wordpress). 🙂

Expand All @@ -12,9 +12,9 @@ To release Gutenberg's npm packages, you need to be part of the [WordPress organ

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.
- **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, a post [like this](https://make.wordpress.org/core/2019/06/26/whats-new-in-gutenberg-26th-june/) describing the changes and performing a [performance audit](/docs/block-editor/contributors/testing-overview/#performance-testing) is published.
- **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, the release post is published, including a [performance audit](/docs/block-editor/contributors/testing-overview/#performance-testing).

If critical bugs are discovered on stable versions of the plugin, patch versions can be released at any time.

Expand Down Expand Up @@ -48,20 +48,22 @@ You should check that folks are able to install the new version from their Dashb

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.

### Writing the Release Notes and Post
### Documenting the release with the Release Notes and Post

Documenting the release is comprised of the following steps:
<div class="callout callout-info">
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.
</div>

1. Curating the changelog
2. Selecting the release highlights
3. Drafting the release post
4. Running the performance tests
5. Publishing the post
1. Curating the changelog - Wednesday after the RC release to Friday
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This timeline is based on recent experience. A delay on a single step makes the rest of the process more time-constrained, resulting in either rushing the post finalization or publishing it late.

2. Selecting the release highlights - Friday to Monday
priethor marked this conversation as resolved.
Show resolved Hide resolved
3. Drafting the release post - Monday to Wednesday
4. Running the performance tests - Wednesday right after the stable release
5. 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 groups them by pull request label.
This is intended to be a starting point for release notes; you will still want to manually review and curate the changelog entries. Because the release candidate changelog is reused in the stable release and it can be a time-consuming process, it is recommended to start this process as soon as the milestone is closed and the release candidate is published.
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:

Expand All @@ -74,19 +76,21 @@ Guidelines for proof-reading include:

#### 2. Selecting the release highlights

Once you have cleaned up the changelog, 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.
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; it is recommended to make this step a collaborative effort and share your picks with the Gutenberg Core team.
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.

#### 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**.

When possible, the highlighted changes in the release post should include an animation (video or GIF) or a static image of them in use. Choosing between an animation or a static image will depend on the best way to showcase each highlight: while animations are better to demonstrate workflows, more direct highlights can be shown with an image; having too many video players adds a layer of friction for users to see the highlight, whereas too many simultaneous animated GIFs can distract and overwhelm the reader.

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. If you would like help creating the visual assets, please ping somebody in the Gutenberg Core team in advance so that it can be planned for.
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.

#### 4. Running the performance tests

Your post should also include a performance audit at the end, comparing the current Gutenberg release with both the previous one and the latest WordPress major version. There are GitHub worfklows in place to do this comparison as part of the Continuous Integration setup, so the performance audit results can be found at the workflow run generated by the release commit in the [Performance Tests workflows](https://github.com/WordPress/gutenberg/actions/workflows/performance.yml) page, with the job name `Compare performance with current WordPress Core and previous Gutenberg versions`.
The post should also include a performance audit at the end, comparing the current Gutenberg release with both the previous one and the latest WordPress major version. There are GitHub worfklows in place to do this comparison as part of the Continuous Integration setup, so the performance audit results can be found at the workflow run generated by the release commit in the [Performance Tests workflows](https://github.com/WordPress/gutenberg/actions/workflows/performance.yml) page, with the job name `Compare performance with current WordPress Core and previous Gutenberg versions`.

If the GitHub workflow fails, the performance audit can be executed locally using `bin/plugin/cli.js perf` and passing as parameters the tags to run the performance suite against, such as `bin/plugin/cli.js perf release/x.y release/x.z wp/a.b`.

Expand All @@ -97,9 +101,7 @@ The performance values usually displayed in the release post are:

#### 5. Publishing the post

Compile this to a draft post on [make.wordpress.org/core](https://make.wordpress.org/core/); this post should be published after the actual release. 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)!

If you don't have access to [make.wordpress.org/core](https://make.wordpress.org/core/), ping someone on the Gutenberg Core team in the [WordPress #core-editor Slack channel](https://wordpress.slack.com/messages/C02QB2JS7) to publish the post.
Copy link
Contributor Author

@priethor priethor Jul 9, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Performing a release, although easier thanks to the current tooling, is still a responsibility and should require being a core contributor.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If this is removed, I'd recommend adding in a line about this being a task for core contributors (I didn't see that noted anywhere yet!).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added that at the top now 👍

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. Drafting the release post - Monday to Wednesday

There is some ambiguity about drafting a post. Wouldn't it be simpler to draft the post on make.wordpress.org/core and in the final step only solidify it and publish? Are there any limitations I should be aware of?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The main drawback of drafting the post directly in make.wordpress.org/core is it makes collaboration harder than, for example, in Google Docs. That is, until collaborative editing is a thing in Gutenberg phase 3, of course 🙂

Copy link
Contributor Author

@priethor priethor Jul 13, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, if the release manager doesn't have editing permissions to make.wordpress.org they would not be able to participate in the drafting, and it would not be possible to share it with individual PR authors to review/add more specifics about complex PR.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The last changes try to clarify that the actual posting needs to be done with somebody already having permissions to publish on make/core, to avoid requiring to grant publishing permissions to one-time authors.

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)!

### Creating Release Candidate Patches (done via `git cherry-pick`)

Expand Down