Enhance npm run since command to support standalone plugins

[felixarntz]

As a follow up to #1064 and #1075 which made the readme changelog NPM script reusable for the standalone plugins as well, this issue is about doing the same for the "since" NPM script, which replaces n.e.x.t placeholders with actual version numbers.

So far the script only supports Performance Lab plugin and requires a --release (-r) argument. We should add a --plugin (-p) argument to it so that a specific plugin slug can be provided. This would then instruct the command to make the replacements only for the specific plugin. For a smooth transition / BC we should use performance-lab as the default for that new argument.

It's worth noting that this unlocks a slightly better workflow experience for publishing plugins. One of the current problems is that when you publish a Performance Lab release, you also publish any pending standalone plugin releases, and it's difficult to figure out whether all plugins that have bumped versions are actually ready because all of this is managed completely manually and intertwined with specific enhancement/bug PRs. While #1061 is the main issue about shaping the future goal, this is unrelated and merely improving the current status quo without actually changing the way we do releases. So it makes sense to be a standalone enhancement.

Here's what having standalone plugin support in our "readme" and "since" commands unlocks:

• Instead of hard-coding specific since annotations when working on enhancement/bug PRs for standalone plugins, we should simply use "n.e.x.t", similar to Performance Lab.
• Similarly, we should no longer bump any standalone plugin versions as part of another enhancement/bug PR.
• Instead, whenever maintainers decide that a specific standalone plugin is ready for release, they would need to do the following:
  • Change the relevant GitHub milestone from using "n.e.x.t" to using the actual version number decided.
  • Open a "release preparation" PR that simply bumps the versions in the plugin main file (header and constant) and readme (header), replaces the plugin's n.e.x.t code placeholders with the correct version (via the "since" NPM script) and populates the readme changelog for that version/milestone (via the "readme" NPM script). This is very similar to what https://make.wordpress.org/performance/handbook/performance-lab/releasing-the-plugin/#preparing-the-release describes for the Performance Lab plugin.

This workflow would notably simplify the current overhead as it would avoid:

• having to manually include those things in specific enhancement/bug PRs
• having to search through the codebase to keep track of which plugins are ready for release (to not accidentally release unfinished standalone plugin updates when releasing a new Performance Lab version)

Going forward, it should be straightforward to know whether a standalone plugin is ready for release by checking whether its latest milestone already has a version number, since the version bumps in the code happen at a similar time. And even if the latter PR is not merged yet, it wouldn't be a problem because the code simply wouldn't be deployed, and it could be done later by dispatching the workflow.

Once the Performance Lab 3.0.0 release has gone out next Monday, I propose we go with the above workflow improvement. It will make standalone plugin releases a more intentional action without changing any technical infrastructure (beyond the "since" script enhancement in this issue). We should then update the relevant documentation here and here to include those preparation steps.

cc @westonruter @mukeshpanchal27 @thelovekesh @joemcgill

[felixarntz]

Here's some proposed content to update https://make.wordpress.org/performance/handbook/performance-lab/releasing-a-standalone-plugin/ with. Specifically, the following should replace the text after the first info notice (starts with "For any plugin to be released, ...") and before describing the release options (ends with "changelog section with all entries for the new version").

Here's a draft:

Preparing for the release

In order for a standalone plugin to be released, its latest milestone needs to have a version specified, and in its code the version needs to be bumped and a changelog added to the readme. So the new version number needs to be decided on.

Please work through the following steps:

1. Locate the latest open GitHub milestone for the specific plugin. Its name should be in the format "{pluginSlug} n.e.x.t".
2. Double check that the relevant PRs for the new release are assigned to this milestone.
3. Rename the milestone to contain the actual version number in place of "n.e.x.t".
4. Create a new branch to prepare the release, either based on trunk, or based on a specific release branch.
5. In that branch, locally run npm run since -- -p {pluginSlug} -r {releaseVersion}.
6. Also run npm run readme -- -m "{pluginSlug} {releaseVersion}" (-m refers to the GitHub milestone).
7. Last but not least, manually update the version number in the following places:
   • in the plugin header in load.php
   • in the PHP constant in load.php
   • in the readme header in readme.txt
8. Double-check and review your changes, in particular the changelog to verify that it looks right.
9. Commit and push the changes and open a new pull request with them, against the branch you originally branched off from.

Once the pull request has been merged into the branch, the plugin can be released from that branch.

Let me know if that makes sense!

[thelovekesh]

@felixarntz Should we opt for managing this through Webpack rather than a custom command? Considering that Webpack now handles all the build steps and is easily adaptable for each scenario, it seems more efficient to leverage its capabilities.

[felixarntz]

@thelovekesh Let's think about that separately. I would like for this issue to focus on the minimum work needed, without involving any refactoring.

If we were to use Webpack for this, we would also need to update the other commands accordingly, all that warrants its own discussion. And if we decide to do it, it would also be a lot more engineering work.

[thelovekesh]

And if we decide to do it, it would also be a lot more engineering work.

Given my experience with this plugin build system, I can assure you that implementing the necessary functionality to transform @since n.e.x.t during file copying will be relatively straightforward. It primarily entails adding an extra function and I can it right away.

If we were to use Webpack for this, we would also need to update the other commands accordingly, all that warrants its own discussion. And if we decide to do it, it would also be a lot more engineering work.

I'll leave that decision up to you, but please be aware that implementing it in either scenario will involve a similar level of effort. This is because each plugin already has its own build system and commands in place, which will need to be considered and integrated accordingly. And I think it would be better to complete this in single run instead of working on the same thing twice.

[felixarntz]

@thelovekesh I don't think this requires a similar level of effort. Even if the engineering execution itself is of similar amount, we would need to define what a Webpack based approach should look like, the API, how it would need to be used, modify the documentation etc.

What I'm proposing here is merely expanding the functionality of the script that already exists, so those additional considerations don't apply for that. No changes required, we're only making an enhancement rather than refactoring.

[thelovekesh]

Agree with the refactoring rationale here, hence update the existing command in #1119