Source block editor docs from WP branch

[chrisvanpatten]

Once #5019 lands, we'll be back to using manifest.json for the sole build of the block editor docs.

Now that we're past the confusion of manifest.json and manifest-devhub.json, I'd like to propose "locking" the block editor docs to the current version of WordPress. Docs for the "bleeding edge" Gutenberg plugin will still be available in the repo. This has been a source of confusion in the past (including for myself, and I know it's happening!) because the developer.wordpress.org site is expected to be the documentation for core, not the plugin.

The easiest way to implement this will be to wait for Gutenberg to create the WP release branch for the 5.4 cycle, and use that in the manifest URL, e.g.:

https://raw.githubusercontent.com/WordPress/gutenberg/wp/5.4/docs/manifest.json

This will mean the process is somewhat manual (it will require a meta commit every time a new major core release occurs) but I think it's the easiest way to make sure the primary documentation source reflects what's in core, rather than the latest changes in the plugin. If this solution is suitable, perhaps there could be an effort during the 5.4 release cycle to see if this can be automated.

[chrisvanpatten]

One thing I didn't think of here is that because the files in the manifest reference the master branch, it could cause it to use the release branch structure while still updating the file contents as PRs are merged in the repo.

Two potential options:

1. Disable the automated sync, and just run it when the meta patch to update the release branch is committed
2. str_replace in the manifest URLs from master to wp/5.4

Even if the automated sync isn't disabled, it's probably still worth consider reducing the sync from 15 minutes to something less frequent (24 hours?) since the release branches won't be regularly updated.

[dd32]

If you work with the expectation that a branch will always be created prior to a WordPress release being made, there's a constant (or two) on WordPress.org that could be used to determine which manifest url to pull from.

Reducing how often the imports run in that case would also make a lot of sense, often enough that an incorrect doc can be updated, but not so often that it's just wasting resources.

[youknowriad]

That's a good proposal I think. Ideally though, we'd have a selector in the handbook to switch between stable and master (and potentially other versions). The reason being that the only way to ensure the building of the handbook went properly is to run it. If we only run it once the branch is created/wp updated, it might be too late and a breakage could go unnoticed.

[chrisvanpatten]

Added a patch to use the wp/5.4 branch. If there's a constant or function which can get the 5.4 value, that'd be even better, but I wasn't aware of one (assuming that .org would generally be reporting trunk?)

[dd32]

Replying to chrisvanpatten:

Added a patch to use the wp/5.4 branch. If there's a constant or function which can get the 5.4 value, that'd be even better, but I wasn't aware of one (assuming that .org would generally be reporting trunk?)

If we can be sure that Gutenberg will always have the branch created prior to the WordPress release being made, we can use the WP_CORE_STABLE_BRANCH constant, which is currently 5.4.

[dd32]

Replying to youknowriad:

Ideally though, we'd have a selector in the handbook to switch between stable and master (and potentially other versions). The reason being that the only way to ensure the building of the handbook went properly is to run it. If we only run it once the branch is created/wp updated, it might be too late and a breakage could go unnoticed.

That's a fair reason not to reduce the import window unless it causes problems.

Adding a second handbook which imports master would be an option, if that was really needed.

[dd32]

In 9678:

Developer: Block Editor Handbook: Import from the WordPress-specific branch.

This allows the handbook to contain information that's relevant to the current release, rather than future changes.

Props chrisvanpatten for initial patch.
Fixes #5020.

[coffee2code]

In 9963:

Developer theme: Revert to once again importing Block Editor handbook from master branch.

Props mkaz.
See #5020.
Fixes #5266.