(For the sake of simplicity, I’ll use Actions For Obsidian as example, but of course the same situation applies to all my apps.)
Changing parameters from one app version to the next, or sunsetting actions entirely, these are interesting topics, even more so since the main interface of my apps is Shortcuts, and therefore all action configuration is handled by Shortcuts. AFO receives no information about the workflows it’s used in, or the big picture. When an action is called by Shortcuts, it’s basically just a function call, where Shortcuts hands over the parameters set by the user but nothing else. The app can work with these parameters, but it can’t overwrite or change them, either.
If it were a standard application, AFO itself would store those values and configurations, and could then run a migration in case an app update would change the makeup of the action’s parameters, e.g. var “File path or title” would become variables “File path” and “title”. The same thing could be done with workflows: If a new action supersedes an old one, a migration could replace the old with the new, and massage the old config to fit the new action.
With Shortcuts, that’s impossible.
So I was pondering how to implement upgrade paths, both in terms of changing parameters, and updating and/or sunsetting actions. Because migrations are out of the question, how do you update something without instantly breaking all workflows relying on that thing?
Here’s what I came up with, an upgrade upgrade split into three phases:
- Changing action parameters while using fallbacks / Adding deprecation notices to actions (current app version, e.g. 2024.2)
- Notifications (current +1, e.g. 2024.3)
- Removal of deprecations and fallbacks (current +X, e.g. 2025.1)
Naturally, when upgrading, AFO would show its change log, where the additions, adjustments, and deprecations are listed. (Ignore at your own leisure.)
Phase 1
Changing action parameters while using fallbacks
Using Get Note’s variable “File path or title” in v2024.1 as an example: If v2024.2 would just replace it with two new variables “File path” and “title”, then the first time you run an existing workflow under v2024.2, Get Note would ask for either file path or title (because both those vars were new and wouldn’t have any values yet), and it’d do that every time you run the workflow until you explicitly set the values in the Shortcuts editor.
Depending on the number of instances of the action in the customer’s workflows, this could get annoying fast, which is not what you want; I’d like to handle it a bit more gentle.
So v2024.2 would change that existing “File path or title” variable to “File path”, and introduce a new var, “Title”. Now the first time v2024.2 runs a workflow with Get Note that is configured to look up a note by its title, the action can fall back to the value of the existing var “File path” (formerly “File path or title”). This way, the execution wouldn’t halt, and we can be reasonably certain that this is what the user wanted because in the previous version, this var would hold the value for both lookup configurations, file path and title.
Adding deprecation notices to actions
Deprecated actions slated for future removal will continue to work until they are removed, but they’ll be marked, like this v2024.2 version of Get Periodic Note:
(Please ignore the styling of the notice, it might change.) So when the customer checks their workflows, the deprecation notice is clearly visible. If they pick it from the list of actions, it’s communicating clearly the preferred alternative.
Phase 2: Notifications
The changed parameters will continue to use fallback values if necessary but they’ll emit notifications now when used (“The parameter X was changed in update Y of AFO, and is currently using a fallback value, please set an explicit value.” or similar.)
Marked actions will continue to work but they, too, will emit notifications now when used (“The action X will be removed in the upcoming update Y of AFO, please replace it.” or similar.)
Phase 3: Removal of deprecations and fallbacks
What it says on the tin.
So that’s where I’m at right now. I just wanted to jot it down to have a post to point to in the future.
If you’re having thoughts on the matter, please voice them, I’m eager for input or maybe even better ways to handle these situations.