WordPress.org

Making WordPress.org

Opened 3 weeks ago

Last modified 2 weeks ago

#5020 new enhancement

Source block editor docs from WP branch

Reported by: chrisvanpatten Owned by:
Milestone: Priority: normal
Component: Developer Hub Keywords:
Cc:

Description

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.

Change History (4)

#1 @chrisvanpatten
3 weeks ago

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.

#2 @dd32
3 weeks ago

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.

This ticket was mentioned in Slack in #core-editor by chrisvanpatten. View the logs.


2 weeks ago

#4 @youknowriad
2 weeks ago

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.

Note: See TracTickets for help on using tickets.