Skip to content

docs: add and update json serialization migration - #10267

Merged
zspriggs merged 1 commit into
RaspberryPiFoundation:mainfrom
zspriggs:json-migration
Aug 12, 2026
Merged

docs: add and update json serialization migration#10267
zspriggs merged 1 commit into
RaspberryPiFoundation:mainfrom
zspriggs:json-migration

Conversation

@zspriggs

Copy link
Copy Markdown
Contributor

The basics

The details

Resolves

Fixes #9468

Proposed Changes

Add JSON serialization migration guide into the docs site.

Also made some edits adjusting the code and wording of the guide, since some of it was outdated:

  • Remove the line about JSON serialization not supporting workspace comment serialization since this is no longer true (see feat: add JSON serialization for workspace comments #7927)
  • Adjust wording on step 1 for blocks and fields. The original doc said that you can stop at this step (after you have JSON wrappers for XML serialization) but since this is essentially what Blockly is already doing behind the scenes, it's a little pointless to stop migration there.
  • Add strong disclaimer about step 3 for blocks, which encourages removal of mutationToDom. There are some issues with removing this function. For example, registerMutators verifies that both mutationToDom and domToMutation are both absent or present, so removing one would throw an error for anyone using registerMutators. These issues are specific to blocks, and don't seem to apply to removing the toXml function on fields after migrating to JSON.
  • Change Blockly.Xml.textToDom to Blockly.utils.xml.textToDom
  • Reformat invalid JSON

Reason for Changes

Previously this document was on Google Docs, which made it impossible for the current team to maintain and a little less visible/accessible for those who needed it. It also needed some updates (details above)

Test Coverage

Claude wrote up some manual tests of the workflows outlined in this doc, I reviewed them

Documentation

n/a

Additional Information

@zspriggs
zspriggs requested a review from a team as a code owner August 12, 2026 15:07
@zspriggs
zspriggs requested a review from lizschwab August 12, 2026 15:07
@github-actions github-actions Bot added the PR: docs Adds or updates documentation label Aug 12, 2026
@zspriggs
zspriggs merged commit a8e9e40 into RaspberryPiFoundation:main Aug 12, 2026
11 checks passed
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.

Convert the "Blockly JSON Serialization Migration Guide" to Markdown

2 participants