Has anyone needed to write custom steps?

I’m in the process of investigating how we’re going to implement real time collaboration with ProseMirror, and trying to wrap my head around the implications of needing to keep client/server code in sync. Specifically I’m thinking about:

  • How frequently am I going to need to make lock-step server/client changes?
  • To what extent should I guard against old clients from interacting with the server?
  • What strategy should I take for data migration?

I’ve been doing a lot of work with ProseMirror schemas, so feel I have a solid grasp on how to change and migrate those, but I haven’t yet needed to implement custom steps.

Has anyone needed to implement custom steps, and if so what was the situation, and why was it necessary? (I’m interested in experiences even if they don’t involve collab)

Now that tables are moving to less rigid schema constraints, I am aware of only one instance where a custom step type was needed – in a schema with nested section nodes, where each level knows its depth (i.e. it’s in the node type, not implicit in the amount of parent sections), ‘lifting’ or ‘raising’ section requires a step that increments or decrements the level of all child sections. (This was relatively easy to write, and the lifting/raising naturally produce inversions of each other, which seems to validate the extensible-step concept.)

After 1.0, it should no longer happen that changes to the model or the way steps work ever require a lockstep upgrade. In fact, for most recent new versions, my collab demo continued working after I updated the client and before I restarted the server, since there’s been very little churn in that part of the code.

But if you change your schema, you’ll probably want both sides to use the same schema. Even if a change is non-breaking (leaving all old document valid under the new schema), the client will have to be able to handle being sent documents that contain elements that didn’t exist in the old schema, so you’ll probably want to build some kind of version-check into your protocols.


So it sounds like the workflow for adding a new step would be pretty simple:

  1. Update server software to include the new step.
  2. Update client software to include the new step.

Changes to the behaviour of an existing step should either:

  • never be done
  • require a lock-step change to client/server