Docs: Fix stale, incorrect, or missing documentation by sirreal · Pull Request #78686 · WordPress/gutenberg

sirreal · 2026-05-26T13:37:42Z

What?

Update documentation across the project where docs were found to be stale, incorrect, or otherwise lacking.

Use of AI Tools

Claude was used to analyze the state of documentation and make updates and corrections.

sirreal · 2026-05-26T13:38:33Z

@@ -48,6 +52,12 @@ New styles options are integrated into theme.json on a regular basis. Knowing th
 | `spacing.margin.left`         | 5.8 | 5.9 |
 | `spacing.margin.bottom`       | 5.8 | 5.9 |
 | `spacing.blockGap`            | 5.9 | 5.9 |
+| `background.backgroundAttachment` | 6.6 | 6.6 |
+| `background.backgroundImage`      | 6.6 | 6.5 |
+| `background.backgroundPosition`   | 6.6 | 6.6 |
+| `background.backgroundRepeat`     | 6.6 | 6.6 |
+| `background.backgroundSize`       | 6.6 | 6.6 |
+| `dimensions.aspectRatio`      | 6.6 | 6.6 |


These require careful review for correctness.

Maybe @andrewserong or @aaronrobertshaw can help here?

Copilot · 2026-05-26T14:31:33Z

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

translate.wordpress.org
- Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node node i18n-cache/index.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Configure Actions setup steps to set up my environment, which run before the firewall is enabled
Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Agent-Logs-Url: https://github.com/WordPress/gutenberg/sessions/de000182-c0aa-45a7-b46a-8b6ba9f0b733

github-actions · 2026-05-26T14:39:53Z

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.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @Copilot.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

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

Unlinked contributors: Copilot.

Co-authored-by: sirreal <jonsurrell@git.wordpress.org>
Co-authored-by: mirka <0mirka00@git.wordpress.org>
Co-authored-by: ntsekouras <ntsekouras@git.wordpress.org>

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

sirreal · 2026-05-26T14:40:31Z

 | [no-dom-globals-in-module-scope](https://github.com/WordPress/gutenberg/tree/HEAD/packages/eslint-plugin/docs/rules/no-dom-globals-in-module-scope.md)               | Disallow use of DOM globals in module scope.                                                    |             |
 | [no-dom-globals-in-react-cc-render](https://github.com/WordPress/gutenberg/tree/HEAD/packages/eslint-plugin/docs/rules/no-dom-globals-in-react-cc-render.md)         | Disallow use of DOM globals in React class component render methods.                            |             |
 | [no-dom-globals-in-react-fc](https://github.com/WordPress/gutenberg/tree/HEAD/packages/eslint-plugin/docs/rules/no-dom-globals-in-react-fc.md)                       | Disallow use of DOM globals in the render cycle of a React function component.                  |             |
+| [no-ds-tokens](https://github.com/WordPress/gutenberg/tree/HEAD/packages/eslint-plugin/docs/rules/no-ds-tokens.md)                                                   | Disallow any usage of `--wpds-*` CSS custom properties.                                         |             |


@mirka or @ciampo - are these rules OK to add to the eslint-plugin readme?

It looks like I didn't include it in the readme because tokens were not yet public at the time (#75872), but it's fine now 👍 Thanks.

Copilot

Pull request overview

This docs-only PR refreshes stale documentation across Gutenberg references, tutorials, package READMEs, and contributor guides.

Changes:

Updates stale links, command names, imports, and code examples.
Adds missing references for newer block/theme.json settings and ESLint rules.
Corrects documentation examples for filters, InnerBlocks JSX, block transforms, and private APIs.

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
`packages/eslint-plugin/README.md`	Adds recently introduced ESLint rules to the rules table.
`packages/create-block/README.md`	Updates the default create-block template name.
`packages/babel-preset-default/README.md`	Updates the example Babel plugin.
`docs/reference-guides/theme-json-reference/styles-versions.md`	Adds newer theme.json style properties and versions.
`docs/reference-guides/interactivity-api/directives-and-store.md`	Clarifies the planned WordPress 7.0 behavior change.
`docs/reference-guides/interactivity-api/core-concepts/server-side-rendering.md`	Fixes object syntax in a store example.
`docs/reference-guides/filters/block-filters.md`	Updates render block filter examples to accept three args.
`docs/reference-guides/block-api/block-transforms.md`	Fixes JavaScript syntax in transform examples.
`docs/reference-guides/block-api/block-supports.md`	Adds dimensions aspect ratio support and fixes example commas.
`docs/reference-guides/block-api/block-edit-save.md`	Adjusts a save example variable declaration.
`docs/reference-guides/block-api/block-context.md`	Adds a missing i18n import to an example.
`docs/reference-guides/block-api/block-bindings.md`	Updates the supported-attribute extension example.
`docs/reference-guides/block-api/block-attributes.md`	Fixes key-concepts anchor links.
`docs/reference-guides/block-api/block-api-versions/block-migration-for-iframe-editor-compatibility.md`	Updates iframe-editor conditions and compose imports.
`docs/private-apis.md`	Updates listed private block-editor exports.
`docs/how-to-guides/themes/theme-support.md`	Refreshes appearance-tools coverage.
`docs/how-to-guides/metabox.md`	Fixes the plugin sidebar tutorial link.
`docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md`	Fixes JSX comment syntax.
`docs/explanations/architecture/styles.md`	Updates `useSetting` reference to `useSettings`.
`docs/explanations/architecture/performance.md`	Updates performance test paths.
`docs/contributors/folder-structure.md`	Corrects the `lib/compat` directory name.
`docs/contributors/code/release/plugin-release.md`	Updates the cherry-pick npm script name.
`docs/contributors/code/managing-packages.md`	Fixes the release process anchor link.
`docs/contributors/code/coding-guidelines.md`	Updates the private settings file path.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+| [no-global-active-element](https://github.com/WordPress/gutenberg/tree/HEAD/packages/eslint-plugin/docs/rules/no-global-active-element.md)                           | Disallow accessing the active element via `document.activeElement`.                             | ✓           |
+| [no-global-get-selection](https://github.com/WordPress/gutenberg/tree/HEAD/packages/eslint-plugin/docs/rules/no-global-get-selection.md)                             | Disallow accessing the selection via `window.getSelection`.                                     | ✓           |


 {
 	"presets": [ "@wordpress/babel-preset-default" ],
-	"plugins": [ "@babel/plugin-transform-class-properties" ]
+	"plugins": [ "@babel/plugin-proposal-decorators" ]


github-actions · 2026-05-26T15:12:11Z

Flaky tests detected in e6ac37f.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/26455140479
📝 Reported issues:

[Flaky Test] should be able to open the tags panel and create a new tag #59638 in /test/e2e/specs/editor/various/taxonomies.spec.js

sirreal added the [Type] Developer Documentation Documentation for developers label May 26, 2026

sirreal commented May 26, 2026

View reviewed changes

Comment thread docs/reference-guides/theme-json-reference/styles-versions.md

Copilot started work on behalf of sirreal May 26, 2026 14:25 View session

Copilot finished work on behalf of sirreal May 26, 2026 14:33

sirreal added 24 commits May 26, 2026 16:39

Docs fix: coding-guidelines privateSettings path

cb80468

Docs fix: managing-packages anchor link

c902c2a

Docs fix: plugin-release cherry-pick script name

6625cd8

Docs fix: folder-structure (lib/compact -> lib/compat)

351a108

Docs fix: performance.md folder paths

87a5a70

Docs fix: styles.md useSetting -> useSettings

724a4e8

Docs fix: nested-blocks-inner-blocks JSX comment

ce50aea

Docs fix: metabox.md broken sidebar tutorial link

b361983

Docs fix: theme-support appearance tools opt-ins

5619b4c

Docs fix: private-apis.md stale block-editor exports

6ae24d5

Docs fix: block-migration-for-iframe-editor-compatibility

b688c3e

Docs fix: block-attributes anchors

6c85a42

Docs fix: block-bindings supported-attributes example

ef123ec

Docs fix: block-context example missing i18n import

d063fdf

Docs fix: block-edit-save const-to-let

9551eed

Docs fix: block-supports.md dimensions subproperties and example

9700aa4

Docs fix: block-transforms.md syntax errors

120fdc2

Docs fix: block-filters accepted_args

f7a3259

Docs fix: server-side-rendering missing comma in JS example

9255215

Docs fix: directives-and-store withSyncEvent version

38d0b50

Docs fix: styles-versions.md add missing keys

7e3ba61

Docs fix: babel-preset-default README example plugin

c68a2b8

Docs fix: create-block default template name

6c5dce0

Docs fix: eslint-plugin README rules table

b496f09

docs: correct style version entries for text indent and background props

e6ac37f

Agent-Logs-Url: https://github.com/WordPress/gutenberg/sessions/de000182-c0aa-45a7-b46a-8b6ba9f0b733

sirreal marked this pull request as ready for review May 26, 2026 14:39

sirreal requested review from ajitbohra, fabiankaegy, gziolo, juanmaguitar, nerrad, ntwb and ryanwelcher as code owners May 26, 2026 14:39

sirreal force-pushed the docs-fix-scaled-integration branch from 93372e1 to e6ac37f Compare May 26, 2026 14:39

sirreal requested review from ajitbohra, fabiankaegy, gziolo, juanmaguitar, nerrad, ntwb and ryanwelcher as code owners May 26, 2026 14:39

sirreal commented May 26, 2026

View reviewed changes

sirreal requested review from Copilot and ntsekouras May 26, 2026 14:40

Copilot started reviewing on behalf of sirreal May 26, 2026 14:42 View session

Copilot AI reviewed May 26, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: Fix stale, incorrect, or missing documentation#78686

Docs: Fix stale, incorrect, or missing documentation#78686
sirreal wants to merge 25 commits into
trunkfrom
docs-fix-scaled-integration

sirreal commented May 26, 2026

Uh oh!

sirreal May 26, 2026

Uh oh!

ntsekouras May 26, 2026

Uh oh!

Uh oh!

Copilot AI commented May 26, 2026

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

github-actions Bot commented May 26, 2026 •

edited

Loading

Uh oh!

sirreal May 26, 2026

Uh oh!

mirka May 26, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

github-actions Bot commented May 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

		\| [no-global-active-element](https://github.com/WordPress/gutenberg/tree/HEAD/packages/eslint-plugin/docs/rules/no-global-active-element.md) \| Disallow accessing the active element via `document.activeElement`. \| ✓ \|
		\| [no-global-get-selection](https://github.com/WordPress/gutenberg/tree/HEAD/packages/eslint-plugin/docs/rules/no-global-get-selection.md) \| Disallow accessing the selection via `window.getSelection`. \| ✓ \|

Conversation

sirreal commented May 26, 2026

What?

Use of AI Tools

Uh oh!

sirreal May 26, 2026

Choose a reason for hiding this comment

Uh oh!

ntsekouras May 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI commented May 26, 2026

I tried to connect to the following addresses, but was blocked by firewall rules:

Uh oh!

github-actions Bot commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Unlinked Accounts

Uh oh!

sirreal May 26, 2026

Choose a reason for hiding this comment

Uh oh!

mirka May 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

github-actions Bot commented May 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

github-actions Bot commented May 26, 2026 •

edited

Loading