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

priethor · 2021-07-09T11:05:48Z

Description

Updates the Gutenberg release documentation to increase clarity around the release post workflow in terms of:

Timeline between RC and stable releases to avoid late-shipping posts
Ownership of the release post writing and asset creation to provide high-quality content.

priethor · 2021-07-09T11:17:41Z

docs/contributors/code/release.md


 #### 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 written by the release manager or delegated to another core member** agreed upon in advance, **visual assets should be created by the design team**.


The goal of stressing this is to clarify that these are not requirements to perform a release: the post can be written by somebody else if the release manager doesn't feel comfortable writing, whereas design folks can provide awesome assets. Rewrites to convey this message are welcome.

I wouldn't say "should". I'd say "visual assets are created by the design team." If possible, would be good to make it bit clearer where to get help (could be as simple as going to the #design channel).

Yeah, this comment got outdated as the edit didn't feel right and later switched it to:

visual assets are best created by the design team

But your suggestion is even better 💯

priethor · 2021-07-09T11:19:26Z

docs/contributors/code/release.md

@@ -93,9 +98,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.


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

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

Added that at the top now 👍

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?

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 🙂

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.

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.

priethor · 2021-07-09T11:21:22Z

docs/contributors/code/release.md

+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.
+</div>
+
+1. Curating the changelog - Wednesday after the RC release to Friday


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.

annezazu

Left some minor suggestions to take or leave but otherwise approved!

docs/contributors/code/release.md

annezazu · 2021-07-09T17:09:25Z

docs/contributors/code/release.md


 #### 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 written by the release manager or delegated to another core member** agreed upon in advance, **visual assets should be created by the design team**.


I wouldn't say "should". I'd say "visual assets are created by the design team." If possible, would be good to make it bit clearer where to get help (could be as simple as going to the #design channel).

annezazu · 2021-07-09T17:10:20Z

docs/contributors/code/release.md

@@ -93,9 +98,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.


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

priethor · 2021-07-09T17:40:28Z

docs/contributors/code/release.md

@@ -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/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).


Not being a Gutenberg team member means handling the release without having made a couple of PRs and also adds overhead to the process, as the release manager needs to be granted permissions to access GitHub workflows and publish the release post.

I agree that it makes sense to add this limitation. It's still a very large group of contributors that can perform the Gutenberg release.

gziolo · 2021-07-12T06:50:53Z

docs/contributors/code/release.md

@@ -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](#writing-the-release-notes-and-post) and spans until the final release.


#writing-the-release-notes-and-post link is outdated.

Thanks, I fixed this and another similar one 👍

gziolo

It's great to see all the details shared about the process of compiling the release notes.

I had some minor comments, but otherwise, it looks great.

One thing that I would consider is to encourage folks (who can edit PR titles) to go through the release milestone and fix typos in PRs before running the RC so the same changes are reflected on GitHub, too.

…ke/core

priethor added the [Type] Developer Documentation Documentation for developers label Jul 9, 2021

priethor self-assigned this Jul 9, 2021

priethor commented Jul 9, 2021

View reviewed changes

priethor marked this pull request as ready for review July 9, 2021 11:25

priethor requested review from ajitbohra and chrisvanpatten as code owners July 9, 2021 11:25

priethor requested review from mtias, kellychoffman, youknowriad, gziolo and annezazu July 9, 2021 11:25

annezazu approved these changes Jul 9, 2021

View reviewed changes

priethor commented Jul 9, 2021

View reviewed changes

gziolo reviewed Jul 12, 2021

View reviewed changes

gziolo approved these changes Jul 12, 2021

View reviewed changes

priethor added 9 commits July 14, 2021 11:54

Update release process documentation

4335cac

Fix typos and formatting.

e3e2ab3

Fix formatting.

cf22f53

Rewording to avoid second person.

e466c4d

Update release.md

330dd24

Add a reference to being pinged to coordinate

b6916ed

Update Gutenberg membership requirements.

cac4953

Fix internal handbook links

93ab896

Reword the drafting and publishing, clarify permissions to post on ma…

56eb56e

…ke/core

priethor force-pushed the docs/update-gutenberg-release-post-creation-process branch from 052f274 to 56eb56e Compare July 14, 2021 09:55

priethor merged commit a5e89d4 into trunk Jul 14, 2021

priethor deleted the docs/update-gutenberg-release-post-creation-process branch July 14, 2021 11:34

github-actions bot added this to the Gutenberg 11.1 milestone Jul 14, 2021

priethor mentioned this pull request Jul 19, 2021

Automate grouping of release Changelog PRs by feature #33229

Merged

12 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

priethor commented Jul 9, 2021

priethor Jul 9, 2021

annezazu Jul 9, 2021

priethor Jul 9, 2021

priethor Jul 9, 2021 •

edited

Loading

annezazu Jul 9, 2021

priethor Jul 9, 2021

gziolo Jul 12, 2021

priethor Jul 13, 2021

priethor Jul 13, 2021 •

edited

Loading

priethor Jul 13, 2021

priethor Jul 9, 2021

annezazu left a comment

annezazu Jul 9, 2021

annezazu Jul 9, 2021

priethor Jul 9, 2021

gziolo Jul 12, 2021

gziolo Jul 12, 2021

priethor Jul 13, 2021

gziolo left a comment


		#### 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 written by the release manager or delegated to another core member agreed upon in advance, visual assets should be created by the design team.

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

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

Conversation

priethor commented Jul 9, 2021

Description

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

priethor Jul 9, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

priethor Jul 13, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

annezazu left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gziolo left a comment

Choose a reason for hiding this comment

priethor Jul 9, 2021 •

edited

Loading

priethor Jul 13, 2021 •

edited

Loading