Streamline PL and standalone plugins release

[thelovekesh]

Currently, when a new PL plugin version gets released two workflows get triggered:

• Deploy to WordPress.org (Deploy Performance Plugin)
• Deploy Standalone Plugins (Deploy each standalone plugin)

But the standalone plugins can also be deployed using the workflow_dispatch trigger which does not require any release to be created. As mentioned by @westonruter, in this case there will be no record for such plugin which are deployed manually on workflow_dispatch trigger - #1033 (comment)

TODO

• Streamline plugin release and release notes.

(More TODOs can be added with ongoing discussion)

[felixarntz]

@thelovekesh What are our options here?

The approach that quickly comes to mind is to create GitHub releases for the individual products and then the workflows act accordingly, e.g. based on the release name. For example, we could make it so that a release named webp-uploads 1.0.6 triggers a deployment of the webp-uploads plugin at version 1.0.6. That's one way.

Alternatively, we could consider having a workflow that even creates the release for us. That would be even more efficient because all information is already present:

• The version number would be in the code and readme.
• The changelog would be in the readme.
  A workflow could extract that and create the release automatically, and then also deploy.

There are probably alternative approaches too. Let's brainstorm and discuss our options a bit, and then make a decision before starting with the implementation.

[thelovekesh]

@felixarntz If we go with creating separate releases for each standalone plugin, we will be bombarded with release entries on the releases page. Another approach that comes to my mind is to keep two release workflows:

• Performance Lab Plugin - The release title can be Performance Lab 3.0.0

  Release changelog example

  Features
  // Futher details.

  Enhancements
  // Futher details.

  Bug Fixes
  // Futher details.

• Performance Lab Features - The release title can be Performance Lab Featutres 1.0.0
  

  Release changelog example

  WebP Uploads - 1.0.3

  Features
  // Futher details.

  Enhancements
  // Futher details.

  Bug Fixes
  // Futher details.

  Speculation Rules - 1.2.0

  Features
  // Futher details.

  Enhancements
  // Futher details.

  Bug Fixes
  // Futher details.

It will help us to keep the release entires minimal and changelogs are better organized.

[westonruter]

Why would it be hard to track release logs if PRs are assigned plugin-specific milestones?

[thelovekesh]

Why would it be hard to track release logs if PRs are assigned plugin-specific milestones?

I meant release entries on the release page. Sorry for the confusion. I have updated the comment above.

[swissspidy]

Since we're talking about releases and deployments here:

What works well for plugins like Gutenberg and Web Stories is to use deployments as the entrypoint for publishing new versions (rather than the release being the entrypoint). For example, if you want to ship a new version of the plugin:

1. Manually dispatch/trigger the release workflow on GitHub
2. Thanks to environment protection, someone needs to approve this "deployment"
3. The workflow then updates the version numbers, changelogs, creates a GitHub release, etc., and uploads the plugin to WordPress.org

Advantage: very easy to use, extra safety due to environment protection, no code changes needed to release a new version.

If we go with creating separate releases for each standalone plugin, we will be bombarded with release entries on the releases page

I wouldn't say "bombarded". It's not like we're doing 1 release a day or so. So I don't think this is really a problem. The "Performance Lab Features" idea is interesting but IMHO a bit overkill.

GitHub releases aren't really the source of truth. People will go to WordPress.org and WordPress admin to install plugins and get new versions.

[thelovekesh]

Before we start, let's also gather info on:

• Are we using the 'n.e.x.t' versioning for all plugins?
• Do we need a release branch for all plugins or just the PL one?

[felixarntz]

@thelovekesh

Are we using the 'n.e.x.t' versioning for all plugins?

I just opened #1118 in that regard. In other words, yes we should. We just can't until the npm run since command has been enhanced to support the other plugins (which is the technical enhancement that issue proposes).

Having to put specific versions on code in PRs before we even know when it will be released or in which versions is a poor experience and requires a lot of manual oversight. It often means we add a version number and bump the plugin version preliminarily. See the new issue for more context.

[thelovekesh]

As discussed in the previous Performance chat, here are the steps we can follow to automate the release along with automating:

• The plugin-name-n.e.x.t milestone name with the plugin-name-x.x.x version and create a new milestone with previous name i.e. plugin-name-n.e.x.t.
• Release branch creation and update the @since tag on the trunk.
• Changelog generation. Instead of manually adding changelog to the readme.txt, we add = n.e.x.t = placeholder and update it with release notes when a new release is created.

Once a release is triggered for a plugin by passing the plugin slug and milestone, the following step takes place:

graph TD;
    A[Trigger release workflow] --> B[Create draft release];
    B --> C[Attach assets to release];
    B --> D[Create release branch, bump version in readme and update n.e.x.t];
    D --> E[Add changelog to plugin];
    D --> G[Create PR with trunk as base];
    G --> H[Attach required information on PR];
    H --> I[Update current milestone];
    I --> J[Create new milestone];

Loading

[swissspidy]

Thanks for putting together a diagram, very helpful!

Why is the draft release with assets created before the version is updated in readme.txt? Why does the workflow create a PR and not just automatically deploy to WordPress.org? Maybe I'm missing something, but IMO we should try to automate as much as possible to remove need for human intervention and errors.

[thelovekesh]

but IMO we should try to automate as much as possible to remove need for human intervention and errors.

Agree 💯!

Why is the draft release with assets created before the version is updated in readme.txt?

Humm that step needs to be removed as it will be covered as part of updating @since n.e.x.t and bumping the version. I have updated it. Other than this,

There are two potential scenarios:

• A release branch is manually created, the version is bumped in the readme, and @since tags are updated within the release branch. Once these steps are completed, the release is finalized.
• Alternatively, this process can be automated, resulting in the creation of a draft release. This draft status allows for a final check to ensure all updates are as expected before officially releasing it, including the changelog, updated files, and more.

Now, regarding the PR aspect, it involves changes from the release branch to the trunk. This is necessary because on the release branch, the readme has an updated version, and changelog and @since n.e.x.t are searched and replaced, and these modifications also need to be merged into the trunk. Presently, this process is manual, but I am suggesting automating it.

[joemcgill]

During the PL 3.2.0 release party today, we revisited the topic of updating the release process so that the releases listed in this repo better reflected all of the plugins and not just the latest Performance Lab release.

Since that is one of the things this issue included in this issue, I propose that we make this an overview issue and keep the issue description up to date with the list of improvements we want to take on as part of this effort, including linking to PRs that have already been implemented related to this effort so it's easier to track progress.

[felixarntz]

@joemcgill @westonruter It looks like some work towards this overview issue has been done (e.g. I spotted #1351). Could one of you please update this issue to point to any related issues/PRs that are in progress or have landed? So that we can keep a better overview of the efforts.

Not sure who of you has been mostly on top of this one, but it would be great if one of you could provide a brief update on where this overall effort is at. For instance in regards to:

• I see https://github.com/WordPress/performance/releases now has the plugin ZIPs for all plugins that were released, but as far as I can tell the description is still the changelog for just the PL plugin. Is that correct?
• If so, are we planning to expand the GitHub release notes to have the changelogs for all plugins that were released? Or is the idea to publish individual GitHub releases per plugin in the future?
• Has anything in the requirements for preparing or publishing a release changed? For instance, what's the purpose of https://github.com/WordPress/performance/blob/trunk/bin/generate-pending-release-diffs.sh? Is the release documentation under https://make.wordpress.org/performance/handbook/performance-lab/ still up to date?

[westonruter]

I've been managing the releases and working on streamlining aspects of the existing workflow with each release, specifically these pages:

• https://make.wordpress.org/performance/handbook/performance-lab/releasing-the-plugin/
• https://make.wordpress.org/performance/handbook/performance-lab/releasing-a-standalone-plugin/

I've been keeping these handbook pages up to date. If you look at the diff from April to now that might give you a good overview of the improvements for the release process before I get a chance to summarize them better.

For instance, what's the purpose of https://github.com/WordPress/performance/blob/trunk/bin/generate-pending-release-diffs.sh?

This is captured under this section: https://make.wordpress.org/performance/handbook/performance-lab/releasing-the-plugin/#inspect-changes-to-files-in-the-release

I found it to be an important sanity check to ensure that the expected files are present and unexpected files are absent. It was introduced in #1227.

[felixarntz]

@westonruter Thanks for staying on top of that, that's excellent. I just reviewed those updates.

While reviewing and running the enhanced commands for testing, I came up with an idea how we can safeguard this process further, now that it is more automated than before, see #1444.