Skip to content

docs: update serialization docs to reflect support for workspace comments - #10628

Open
ritfiz wants to merge 1 commit into
RaspberryPiFoundation:mainfrom
ritfiz:docs/workspace-comment-serialization
Open

ritfiz wants to merge 1 commit into
RaspberryPiFoundation:mainfrom
ritfiz:docs/workspace-comment-serialization

Conversation

@ritfiz

@ritfiz ritfiz commented Oct 24, 2026

Copy link
Copy Markdown
Contributor

The basics

The details

Resolves

Fixes #10266

Proposed Changes

Updates packages/docs/docs/guides/configure/serialization.mdx:

  • Lists workspace comments as a built-in JSON serializer, next to blocks and variables.
  • Adds workspace comments to the deserialization order. Their priority (WORKSPACE_COMMENTS = 25) is lower than blocks, so they load last.
  • Removes the claim in "Serializer hooks" that workspace comments need a custom serializer.
  • Renames the serializer hooks example from 'workspace-comments' to a generic 'myPlugin' serializer, with matching function names.
  • Keeps { ... } and sample data in the example JSON output, based on the review feedback on fix: correct workspace comment serialization docs #10270.
  • Rewrites the clear example to describe what myPlugin's clear function would do.

Reason for Changes

Workspace comments have had built-in JSON serialization since #7927 (core/serialization/workspace_comments.ts), so the doc was out of date. The old example also suggested that you still had to register a serializer for comments yourself.

Test Coverage

Docs-only change. Ran npx eslint docs/guides/configure/serialization.mdx in packages/docs, and it passes. I did not run a full docs site build.

Documentation

This PR is the documentation update.

Additional Information

The broken "built-in priorities" link mentioned in the issue was already fixed on main by #10405, so this PR doesn't change it.

This picks up the work from #10270, which was closed for inactivity, and includes that PR's review feedback.

🤖 Generated with Claude Code

…ents

Workspace comments have a built-in JSON serializer, so the docs no
longer say a custom serializer is needed for them. The serializer
hooks example now uses a generic plugin serializer instead.

Fixes RaspberryPiFoundation#10266

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ritfiz
ritfiz requested a review from a team as a code owner October 24, 2026 10:00
@ritfiz
ritfiz requested a review from gonfunko October 24, 2026 10:00
@github-actions github-actions Bot added the PR: docs Adds or updates documentation label Oct 24, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

PR: docs Adds or updates documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Update serialization docs to reflect support for workspace comments

2 participants