Parsoid/So you are going to change Parsoid output

This document defines procedures to be followed when modifying the Parsoid output.



Modifying the Parsoid output should, in most cases, be accompanied by an update of the HTML specifications according to the Parsoid HTML Specification Versioning process. This informs the other steps as they depend on whether the change breaks current client expectations or not.

If client expectations are not modified


This is typically a minor or bugfix HTML spec bump. Since the clients would still need to be updated to use the new features, consider the relevance of a Tech News notification.

If clients expectations are modified


This is typically a major HTML spec bump. The following points should be considered; while they may not all be necessary, asking whether they are is essential.

Early notification

  • Make an announcement of the breaking change on Tech News
  • Send an announcement or a RfC to wikitech-l

Prepare client updates

  • Find out whether deployed code may be impacted (Code Search can help with that)
  • Create a client ticket tagging known clients (e.g. task T315209)
  • If realistic, send patches to known clients

Prepare API

  • Is a downgrade path feasible/useful?

Prepare rollout

  • Roll out HTML2WT before WT2HTML
  • Roll out to canary wikis