Add JSON Schema for .wp-env.json files

[fabiankaegy]

Description

This PR adds a JSON Schema for .wp-env.json files.

Closes #36275

[t-hamano]

I came across this PR while checking past PRs.

I also strongly agree with adding this schema 👍 Is it possible to move forward with this PR?

cc @noahtallen @gziolo

[fabiankaegy]

@t-hamano where I failed / left off this PR was in my lack of understanding for how the recursive / nested structure of the .wp-env.json file works for defining multiple environments. And how to properly define that in the schema.

[gziolo]

Great idea, let's bring it to the finish line.

@t-hamano where I failed / left off this PR was in my lack of understanding for how the recursive / nested structure of the .wp-env.json file works for defining multiple environments. And how to properly define that in the schema.

@ajlende, are you able to share any insights that would unblock it?

[ajlende]

I'm not really familiar with wp-env at all—I don't use it myself—but I tried taking a look and guessing at what the intention was.

Hopefully I've made the correct assumptions and my explanations make sense.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: fabiankaegy <fabiankaegy@git.wordpress.org>
Co-authored-by: ajlende <ajlende@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>
Co-authored-by: PerryRylance <perryrylance@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[sirreal]

If the $schema property appears in wp-env configuration, it throws an error:

Invalid /Users/jonsurrell/a8c/wordpress-develop/trunk/.wp-env.json: "$schema" is not a configuration option.

It should allow that property, or possibly even better use the schema to parse configuration.

I created #62619 to track this.

[github-actions]

Warning: Type of PR label mismatch

To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.

• Type-related labels to choose from: [Type] Automated Testing, [Type] Breaking Change, [Type] Bug, [Type] Build Tooling, [Type] Code Quality, [Type] Copy, [Type] Developer Documentation, [Type] Enhancement, [Type] Experimental, [Type] Feature, [Type] New API, [Type] Task, [Type] Technical Prototype, [Type] Performance, [Type] Project Management, [Type] Regression, [Type] Security, [Type] WP Core Ticket, Backport from WordPress Core.
• Labels found: [Type] Enhancement, [Type] Build Tooling, Backported to WP Core, Backport to WP 6.6 Beta/RC.

Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task.

[ajlende]

I added the Backport to WP Beta/RC label so this change along with #62626 and #62634 make it into the wp/6.6 branch. This lets us automatically version our schemas based on WordPress releases. Redirects for WordPress releases are based off the wp/x.x branches and lead to https://schemas.wp.org/wp/x.x/schema.json.

I'm wondering if this schema should be versioned along with WordPress releases, though? Would it make more sense to add redirects for Gutenberg releases (https://github.com/WordPress/gutenberg/tree/v18.5.0) or @wordpress/env releases (https://github.com/WordPress/gutenberg/tree/%40wordpress/env%4010.1.0) instead or in addition to the WordPress ones?

One thing of note with both of those is that they're just tags, so we can't backport missing schema changes like we can with the WordPress releases. We'd have to have some way of finding the latest patch version to redirect if we don't want folks to have to update their $schema for every bug fix.

[t-hamano]

Would it make more sense to add redirects for Gutenberg releases (https://github.com/WordPress/gutenberg/tree/v18.5.0) or @wordpress/env releases (https://github.com/WordPress/gutenberg/tree/%40wordpress/env%4010.1.0) instead or in addition to the WordPress ones?

This makes sense to me. env is a library that does not ship with WordPress core, so I think it might be better to redirect to @wordpress/env releases.

[ellatrix]

I just cherry-picked this PR to the wp/6.6-rc-1 branch to get it included in the next release: 990f23a

[swissspidy]

FWIW this schema is missing things like mysqlPort

[t-hamano]

Thank you for noticing. I compared the env specification and schema again, and as far as I can tell, the following fields are not defined:

• mysqlPort
• testsPort
• lifecycleScripts.afterStart
• lifecycleScripts.afterClean
• lifecycleScripts.beforeDestroy

[t-hamano]

Note: The JSON schema itself is not included in WordPress releases, it exists in the GitHub repository and is simply referenced from the JSON files.

Therefore, if additional fixes can’t be made in time for the WP6.6 release, they can be committed to the wp/6.6 branch (and trunk branch) at a later time.

[bacoords]

@t-hamano I can't find any reference that shows the actual URL of the schema for users to start using it - and I don't see any documentation for it in the package reference.

If there's a preferred URL to the hosted schema I'm happy to add a PR to get this in the package docs: https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/#wp-env-json

[t-hamano]

If there's a preferred URL to the hosted schema I'm happy to add a PR to get this in the package docs:

Thanks for pointing that out! I definitely think references are necessary. The README for the schema itself will also need to be updated.