[SuperEditor] Dos and Donts in commands or reactions when enabling undo/redo

[JostSchenck]

I am aware that undo/redo is in early state and should be considered experimental; I want to understand my part in this as a user before submitting bug reports. I started setting isHistoryEnabled for my outline editor based on super_editor, heavily modified by custom commands and reactions. Of course, I did not expect it to work right away, as I understand that undo/redo poses strong constraints on commands. Reworking my code I got the impression that with a heavily customized editor this is not completely trivial, and maybe it would be a good idea to put together some dos and dont's for the documentation. I'd also like to know if there are things I forgot. For now, I think I identified the following constraints:

1. Any change of state of an Editable must only be done by means of an EditCommand.
2. Every command with HistoryBehavior.undoable must be deterministic in that given the same arguments and the same state of Editables, it must always produce exactly the same new state for all editables. This eg. means that any uuids for newly created nodes must be passed to the command and not generated by it.
3. Every undoable command should not produce any side effects outside of the manipulation of Editables, or at least cause only idempotent side effects.
4. As of 1., reactions that change the state of editables must also only do that by means of commands; side effects in reactions that affect things outside of the editables are also expected to be idempotent.

Is this all I have to take care of or did I forget something? Are there known other traps where one easily violates one of these rules?
And: If I do adhere to the rules above, is it right that to use super_editor's undo/redo mechanism I am only supposed to

• set isHistoryEnabled=true in my Editor and
• implement reset() in my custom document class in a way that the state at initialization is exactly restored, including IDs etc (and be aware that this will later change to the last snapshot being restored)?

@matthew-carroll @angelosilvestre I would be very grateful for any pointers on this. If bringing myself in with developer documentation by writing down all my lessons learned in customizing SuperEditor would be helpful, I'd gladly do so.