Ensure future backwards compatibility

[fwdekker]

Adding backwards compatibility in future versions should be easy. If, in a future version, settings from an older version (>= v3.0.0) are loaded, then an adapter should be invoked that makes the necessary changes in the settings to properly load them without losing anything.

[fwdekker]

cf. https://plugins.jetbrains.com/docs/intellij/persisting-state-of-components.html#migrating-persisted-values

[fwdekker]

I experimented quite a bit with ConverterProvider (knowing it would probably not be quite suitable, but whatever) and found that (1) it does not work with 2022.3 due to a bug causing a deadlock, (2) it always shows a popup when conversion is required, which cannot be skipped to do changes in the background, (3) it was designed to convert project configuration rather than global (plugin) configuration, and (4) looking at how other projects use ConverterProvider, such as autoCP's implementation or PlatformIO's implementation, and copying that implementation, shows to me that most current implementations fail to actually achieve the desired functionality (in these two cases: deleting old run configurations from a project). So to me it looks like this feature is either doesn't work, or is incorrectly used (without any reference implementation to go by).

Reason (3) is already sufficient to ignore the ConverterProvider approach in the first place, but I was curious. Either way, it's not something that I can hack my way around to get this conversion working...

[fwdekker]

Of course, before doing the above experimentation, I tried to follow ConverterProvider's documentation's advice of "do[ing conversion] in com.intellij.openapi.components.PersistentStateComponent's methods or by deprecating [using Storage#deprecated()] its storage", but I haven't been able to figure out an elegant way to do that.

Using deprecation, changes can be slowly replaced over various releases in a sunset-ish way. For example, to rename a field in a persisted class from foo to bar, first add a deprecation tag to foo (resulting in it still loading from old configs, but no longer being stored in new configs) and, when loading the config file, copy foo into bar if needed (using a mechanism that detects whether conversion is needed, either by checking if foo is not null, or by storing and comparing version numbers somehow). However, this has the problem that after conversion, the object is changed but not directly saved (TODO: can this be circumvented?), resulting in the interface showing that something has changed, but it not being visible to the user what has been saved. (Perhaps add a new field to the Settings that indicates whether compatibility changes have been made, and when the UI loads the Settings to be displayed, immediately #applys the changes?)

The drawback of this approach is, of course, that sunsetting isn't very neat, since (very) old configs cannot be converted to the up-to-date format if the sunsetting period has passed. For example, if the sunsetting period is one year, and a user has not updated their plugins in two years, then updating will cause the config to be invalid. (Which may error gracefully, but still, I want the auto-conversion process to just work.)

My other idea is to do something akin to how Death Notifier handles migrations: Check the (old) config's version number, check the plugin's current version number, and apply all intermediate migration code in sequence until the config's format is up to date. Unfortunately, this isn't possible with the default tools because the config is deserialised into the plugin's current definitions of the Settings before Randomness is in control of migrations, which means that old fields which no longer exist in the new plugin are actually discarded before they can be migrated. One way around this would be to serialize the whole thing into, say, JSON using a com.intellij.util.xmlb.Converter passed into Settings using @com.intellij.util.xmlb.annotations.OptionTag, but so far I haven't been able to get that working. Another similar option might be to convert it to an org.jdom.Element (i.e. an XML element), which would follow the convention of using XML. I might try this next.