Wp-Scripts: add new command version-replace

[xaviranik]

What?

This PR adds a new version-replace command in @wordpress/scripts to replace version string
on files for a WordPress plugin.

Why?

fixes #39761

Usage

Add the following to your package.json:

{
    "scripts": {
        "version-replace": "wp-scripts version-replace"
    }
}

Execute npm run version-replace to replace version constant string in files.

Default Configuration

By default, the following files are taken into consideration for version replaced:

[
    'admin/**/*',
    'src/**/*',
    'includes/**/*',
    'templates/**/*',
    'assets/**/*',
    'main-plugin-file.php',
    'uninstall.php',
    'changelog.*',
    'readme.*',
]

Out of the box, the version string constant is your plugin's package.json uppercase name field with _SINCE.
For name field in package.json having value of my-plugin, the version string constant is MY_PLUGIN_SINCE.

More examples:

• for name field value gutenberg: version string constant GUTENBERG_SINCE
• for name field value gutenberg-custom: version string constant GUTENBERG_CUSTOM_SINCE

Customization

By adding the following to your package.json:

• You can use a custom version constant string
• You can override file patterns

{
    "version-replace": {
        "constant": "MY_CUSTOM_CONSTANT",
        "files": [
            "admin/**/*",
            "src/**/*",
            "other-dir/**/*",
            "custom-templates/**/*"
        ]
    }
}

How has this been tested?

I executed the steps manually to test version-replace files with WordPress:

version-replace-wp-scripts.mp4

[github-actions]

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @xaviranik! In case you missed it, we'd love to have you join us in our Slack community, where we hold regularly weekly meetings open to anyone to coordinate with each other.

If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information.

[kevin940726]

I think this is interesting and really helpful, but maybe we could do better given the opportunity?
Instead of asking the developers to fill in the CUSTOM_CONSTANT manually, I think we can just automatically do that before every release.

So an annotate-since script to automatically add @since to every new/changed public API for that version. Similar to what the Playwright repo has been doing, and here’s the result.

This would be a bigger change though, and maybe parsing of the files is required. And I'm also not sure how to do with the manually added @since tag, maybe we'll just have to educate people not to do this anymore? LMK what you think! 😉

[xaviranik]

@kevin940726 Thanks for your insight on this. In simple form, are we talking about this:

A new API is added:

/**
 * Summary.
 * 
 * Description.
 * 
 * @annotate-since
 * 
 * @return type Description.
 */
public function some_new_function() {}

An old API is changed/modified:

/**
 * Summary.
 * 
 * Description.
 * 
 * @since 1.0.0
 * @annotate-since Changed Description.
 * 
 * @return type Description.
 */
public function some_function() {}

So on the Release/Build process, we would ideally run annotate-since script.

Result:

/**
 * Summary.
 * 
 * Description.
 * 
 * @since 1.2.0 Description.
 * 
 * @return type Description.
 */
public function some_new_function() {}

/**
 * Summary.
 * 
 * Description.
 * 
 * @since 1.0.0
 * @since 1.2.0 Changed Description.
 * 
 * @return type Description.
 */
public function some_function() {}

One more thing that I would like to point out is, in the current implementation, we are not bounding the developers to provide the CUSTOM_CONSTANT manually. By default, the script will use the plugin-slug if the custom constant is not provided. Also for the file parsing, by default, we are making sure to adhere to the wp-scripts plugin-zip file descovering. Surely this can be customized with the customization files option provided with the script.

Feel free to let me know your thoughts about this.

[kevin940726]

Hi @xaviranik, sorry for the late reply!

What I meant is to parse all the files and find functions that are added in this release. We can then automatically add @since tag to the docblock. What I didn't consider is the description changelog for each modified function though. I think your solution with @annotate-since makes sense and is probably a better solution.

We can still automatically attach @since for functions that didn't add the @annotate-since annotations. For modified functions that didn't include the changelog, we can add a lint warning to guard against it during code review.

I'm not very familiar with PHP tooling though so not sure about the scope. @gziolo might have a better suggestion or feedback?

[xaviranik]

Hello @gziolo, let us know your thoughts on this. We can move forward with this PR.

[ndiego]

Hi @xaviranik and @gziolo. This PR and associated issue were reviewed in today's Documentation Bug Scrub. We are checking in to see what the current status is. Thanks!

[gziolo]

It's tempting to add more commands to @wordpress/scripts, but it's already been raised as a concern the growing size of the npm package has, which is now at 300 MB with all dependencies. See a comprehensive analysis from @adamziel in WordPress/wordpress-playground#167. I'm aware that the new command is less than 1 Mb with all the dependencies it needs. There is also the documentation aspect attached to it. Every new command makes it harder to discover the most important information that people seek about the core functionality which is building JavaScript and CSS for WordPress blocks.

More importantly, there is also this recurring question how do we decide what to add to the package and what are the criteria, and how can we measure them? My current opinion is that we should seek how to improve the default experience by moving some commands that are non-essential for development purposes to other packages that can be installed on-demand. However, I'm aware that it's a separate discussion to have.