Try: Linting notes - #78880

Size Change: +880 B (+0.01%)

Total Size: 7.74 MB

_{compressed-size-action}

Should we use Notice here? Especially if the plan is to surface warnings and errors here too.

I see where you're coming from, and it's an option. Conceptually it isn't a fit with the idea of notes being a singular surface for anything related to the document. If we think of a note truly as just an annotation, made by a human, a lint tool, an agent, or a suggestion, then each of those are threads that can be discussions as well. Imagine one user hiding a block, then adding a comment below explaining why they hid that block.

My current reservation is that there's still a lot of work to do on the original Notes feature, and it's not flexible. I would like to avoid introducing complexity if we can for the moment.

Thanks so much for looking. I find that to be a solid reason to revert this one to draft.

The principles embedded in this PR, even if not the code, still feels valid to come back to when we have time!

Noting that I have rebased this branch. I'm keeping it draft state, and I'm still thinking of this as a glorified proof of concept or prototype. Whether the largely AI assisted code can grow into a proper branch and land, I've no opinion of, but I think it is useful still to shepherd this along so that we can test and validate the concept. I still think it works.

The rebase entailed removing a lot of bespoke code from this branch, to rather rely on the larger unification work that has happened to notes overall. It's still 14 files changed, but it should be less code do glance through. With no urgency.

Flaky tests detected in 18a22b0.
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/32360531148
📝 Reported tests:

TimeoutError: page.waitForFunction: Timeout 10000ms exceeded.
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/plugins/wp-editor-meta-box.spec.js:34:14
TimeoutError: locator.click: Timeout 10000ms exceeded.
Call log:
  - waiting for locator('role=button[name="Visual"i]')

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/plugins/wp-editor-meta-box.spec.js:33:55

@jasmussen This is really helpful prototype.

Question 1: Is there a way to toggle the floating linting notes?

I appreciate that the hidden-block messages show by default rather than being tucked inside the Notes sidebar. Where I got stuck is turning them off again. I couldn't find a way to get back to a clean view of the page. Once it's known, the user may want to go back to seeing just the design to continue working.

That makes sense for collaboration notes. Someone is waiting on those, and they shouldn't be easy to lose. But I think block status has a different lifecycle:

• A note persists until someone resolves it. It's addressed to a person.
• A status — hidden, locked, etc — is learned once. After that may be noise while you're designing, so the ability to toggle these linting notes might be beneficial.

Question 2: Could linting notes work without the Notes feature turned on?

Do you envision a possibility where these two things could be separated in some way even though they share the same space? Notes is people talking to each other. Block status is the editor telling you what's true about a block. I think right now, any site that doesn't enable Notes, would then lose the benefits of these linting notes.

For example, in our multi-site network, Notes are disabled at this time. See another user who requested a filter for this as well, so it's likely there are other groups who do not enable Notes. From a multisite perspective, I can share more about why we decide to disable them if you're interested. I would just need to speak more with our team to gather more details from the DevOps and support perspective. One of the reasons is that they send email notifications, and our team didn't want to risk that going wrong for hundreds of users.

Solid UX questions, nice.

I appreciate that the hidden-block messages show by default rather than being tucked inside the Notes sidebar. Where I got stuck is turning them off again. I couldn't find a way to get back to a clean view of the page. Once it's known, the user may want to go back to seeing just the design to continue working.

There's an ongoing effort relating to Notes in general, for how to show them, which would include this. One of the efforts that @annezazu and I believe @Mamaduka have been working on is a toggle to choose the appearance: full, compact, or possibly entirely hidden (i.e. have to click the Notes toolbar button). There's also a mockup here, which adds a collapse button to the vertical separator between notes and canvas. However part of the concept of these linting notes is to make them extremely obvious first and foremost, and secondly treat them solely as "Notes", ones that the system has authored rather than a user.

You make a good point, however:

That makes sense for collaboration notes. Someone is waiting on those, and they shouldn't be easy to lose. But I think block status has a different lifecycle:

• A note persists until someone resolves it. It's addressed to a person.
• A status — hidden, locked, etc — is learned once. After that may be noise while you're designing, so the ability to toggle these linting notes might be beneficial.

Indeed these linting notes would not be dismissible as such, at least not without adjustments to the concept presented here, so this is a good note. That being said, an adjustment would be to simply allow you to turn off linting notes in the canvas, perhaps in the same "compact" menu as the one Anne and George have been looking towards.

Mainly, the motivation for using Notes, aside embracing an existing interface, is that hidden block and probably responsive styles should likely be obvious, always, that's the consistent feedback we've heard across a variety of different issues: people are looking for interfaces that surface these blocks.

Generally the instincts go towards adding more indicators to the List View, which we can, it's just already relatively heavy on UI. Another instinct is a new panel in the document inspector: "Lint"—or a better term, that simply lists out issues. It's not clear any of those are obious enough, however, but I still think we could do both, that they can coexist and complement each other. E.g. both a Lint panel and in-canvas notes; if you end up toggling off the in-canvas notes, you'll still have the panel.

Mostly I'm also just encouraging of PRs that start with minimal solutions: e.g. if it's easier to start with a panel than with in-canvas Notes, let's start there. We might even find it sufficient, in which case this prototype will also have served its purpose. Is that fair?

There's an ongoing effort relating to Notes in general, for how to show them, which would include this. One of the efforts that @annezazu and I believe @Mamaduka have been working on is a toggle to choose the appearance: full, compact, or possibly entirely hidden (i.e. have to click the Notes toolbar button). There's also a mockup here, which adds a collapse button to the vertical separator between notes and canvas. However part of the concept of these linting notes is to make them extremely obvious first and foremost, and secondly treat them solely as "Notes", ones that the system has authored rather than a user.

I like the direction of the toggle to choose the appearance; that solves the challenge nicely!

However part of the concept of these linting notes is to make them extremely obvious first and foremost, and secondly treat them solely as "Notes", ones that the system has authored rather than a user.

This framing was helpful framing for me: notes the system authors versus the user. Thank you!

Generally the instincts go towards adding more indicators to the List View, which we can, it's just already relatively heavy on UI. Another instinct is a new panel in the document inspector: "Lint"—or a better term, that simply lists out issues. It's not clear any of those are obvious enough, however, but I still think we could do both, that they can coexist and complement each other. E.g. both a Lint panel and in-canvas notes; if you end up toggling off the in-canvas notes, you'll still have the panel.

Mostly I'm also just encouraging of PRs that start with minimal solutions: e.g. if it's easier to start with a panel than with in-canvas Notes, let's start there. We might even find it sufficient, in which case this prototype will also have served its purpose. Is that fair?

Yes! Absolutely. I agree with you that there's room to both, and agree about PRs that start with minimal solutions. I'll continue to follow the Notes discussion! Thinking only of users, and not the nuances with different site setups, it sounds like the Notes solution might solve the need you're hearing from users the best, so that this information is always obvious in the editor rather than hidden from the user behind a tab or separate panel.

I would still advocate for a way to enable Notes with the option to filter out author notes, so that groups like ours could benefit from the system notes too. But I can understand that it might not be feasible for the Notes feature itself. We could put our efforts towards helping shape a complimentary "Lint" tab for groups like ours. I know there must be a better term, but I can't think of one right now :)

Rebased.

🤖 PR meta 🤖

🎉 Props

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: jasmussen <joen@git.wordpress.org>
Co-authored-by: jameskoster <jameskoster@git.wordpress.org>
Co-authored-by: Mamaduka <mamaduka@git.wordpress.org>
Co-authored-by: kedarjoyner <kjoyner@git.wordpress.org>

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

Updated as activity occurs, without notifying anyone named here. Add the props-bot label to refresh.

📦 Bundle size

Size Change: +830 B (+0.01%)

Total Size: 9.05 MB

_{dcdec4e Run}

⚡ Performance

_{dcdec4e Run}

🏁 Flaky tests

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.

Error: expect(received).toStrictEqual(expected) // deep equality

- Expected  - 1
+ Received  + 1

  Array [
    "rewrite_rules",
-   "SERIALIZED DATA",
+   "",
  ]
    at forEach (/home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/core-settings.spec.js:46:26)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/core-settings.spec.js:43:35

TypeError: Cannot read properties of null (reading 'y')
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/draggable-blocks.spec.js:824:57
    at dragSelectionBelowLanding (/home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/draggable-blocks.spec.js:823:3)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/draggable-blocks.spec.js:908:3

Error: expect(received).toHaveLength(expected)

Expected length: 0
Received length: 1
Received array:  [{"_links": {"about": [{"href": "http://localhost:8889/wp-json/wp/v2/types/attachment"}], "author": [{"embeddable": true, "href": "http://localhost:8889/wp-json/wp/v2/users/1"}], "collection": [{"href": "http://localhost:8889/wp-json/wp/v2/media"}], "curies": [{"href": "https://api.w.org/{rel}", "name": "wp", "templated": true}], "replies": [{"embeddable": true, "href": "http://localhost:8889/wp-json/wp/v2/comments?post=223"}], "self": [{"href": "http://localhost:8889/wp-json/wp/v2/media/223", "targetHints": {"allow": ["GET", "POST", "PUT", "PATCH", "DELETE"]}}], "wp:attached-to": [{"embeddable": true, "href": "http://localhost:8889/wp-json/wp/v2/posts/222", "id": 222, "post_type": "post"}]}, "alt_text": "", "author": 1, "caption": {"rendered": ""}, "class_list": ["post-223", "attachment", "type-attachment", "status-inherit", "hentry", "entry"], "comment_status": "open", "date": "2026-10-22T09:14:01", "date_gmt": "2026-10-22T09:14:01", "description": {"rendered": "<p class=\"attachment\"><a href='http://localhost:8889/wp-content/uploads/2026/10/aea6734a-26f7-4fb8-8e87-af05401f05f0.png'><img loading=\"lazy\" decoding=\"async\" width=\"10\" height=\"10\" src=\"http://localhost:8889/wp-content/uploads/2026/10/aea6734a-26f7-4fb8-8e87-af05401f05f0.png\" class=\"attachment-medium size-medium\" alt=\"\" style=\"width:100%;height:100%;max-width:10px;\" /></a></p>
"}, "featured_media": 0, "filename": "aea6734a-26f7-4fb8-8e87-af05401f05f0.png", "filesize": 80, "guid": {"rendered": "http://localhost:8889/wp-content/uploads/2026/10/aea6734a-26f7-4fb8-8e87-af05401f05f0.png"}, "id": 223, "link": "http://localhost:8889/?attachment_id=223", "media_details": {"file": "2026/10/aea6734a-26f7-4fb8-8e87-af05401f05f0.png", "filesize": 80, "height": 10, "image_meta": {"alt": "", "aperture": "0", "camera": "", "caption": "", "copyright": "", "created_timestamp": "0", "credit": "", "focal_length": "0", "iso": "0", "keywords": [], "orientation": "0", "shutter_speed": "0", "title": ""}, "sizes": {}, "width": 10}, "media_type": "image", "meta": [], "mime_type": "image/png", "modified": "2026-10-22T09:14:01", "modified_gmt": "2026-10-22T09:14:01", "ping_status": "closed", "post": 222, "slug": "aea6734a-26f7-4fb8-8e87-af05401f05f0", "source_url": "http://localhost:8889/wp-content/uploads/2026/10/aea6734a-26f7-4fb8-8e87-af05401f05f0.png", "status": "inherit", "template": "", "title": {"rendered": "aea6734a-26f7-4fb8-8e87-af05401f05f0"}, "type": "attachment"}]
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/single-file-placeholder-drop.spec.js:71:45

TimeoutError: locator.waitFor: Timeout 17500ms exceeded.
Call log:
  - waiting for getByRole('button', { name: /Collaborators list/ }) to be visible

    at map (/home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/collaboration/fixtures/collaboration-utils.ts:193:7)
    at CollaborationUtils.waitForMutualDiscovery (/home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/collaboration/fixtures/collaboration-utils.ts:188:10)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/collaboration/collaboration-stress.spec.ts:416:28

_{dcdec4e Run}

Rebased on current trunk. This is the state, still just showing a lint note for a fully hidden block:

This message is for the Notes maintainers already subscribed, not necesarily to respond to urgently—I know we're busy with 7.2 beta. But I still think the concept of this branch is valid: notes are messages however they got added, and a hidden block is worth knowing about just like a suggestion or comment from a user. So let me know when we ready to look at this as something we can potentiallymerge.

In maintaining this branch, it still doesn't fork any of the notes plumbing: lint findings are just entries in the same threads list Notes already renders, floating off the same board, so each card tracks its block exactly like a note does.

As part of the rebase, block-editor no longer unmounts hidden blocks when they're deselected, since otherwise there's no rect to anchor to, and calculateNotePositions now falls back to the first measurable thread as its anchor, which added the nice little nimation. One caveat I'd want your eyes on: useLintItems derives findings from the block tree on every store change, which re-renders Notes — that cuts against the board's don't-re-render-on-canvas-changes principle, and I'd rather fix it the way you'd want it fixed than guess.