WordPress.org

Making WordPress.org

Opened 9 months ago

Closed 7 months ago

Last modified 5 months ago

#5020 closed enhancement (fixed)

Source block editor docs from WP branch

Reported by: chrisvanpatten Owned by: dd32
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.

Attachments (1)

5020.diff (821 bytes) - added by chrisvanpatten 7 months ago.

Download all attachments as: .zip

Change History (13)

#1 @chrisvanpatten
9 months 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
9 months 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.


9 months ago

#4 follow-up: @youknowriad
9 months 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.

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


7 months ago

@chrisvanpatten
7 months ago

#6 follow-up: @chrisvanpatten
7 months ago

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?)

This ticket was mentioned in Slack in #meta-devhub by chrisvanpatten. View the logs.


7 months ago

#8 in reply to: ↑ 6 @dd32
7 months ago

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.

#9 in reply to: ↑ 4 @dd32
7 months ago

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.

#10 @dd32
7 months ago

  • Owner set to dd32
  • Resolution set to fixed
  • Status changed from new to closed

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.

This ticket was mentioned in Slack in #meta by ocean90. View the logs.


5 months ago

#12 @coffee2code
5 months ago

In 9963:

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

Props mkaz.
See #5020.
Fixes #5266.

Note: See TracTickets for help on using tickets.