Investigate Vortex update flow

[insomnious]

Spike

There are many aspects of Vortex's update flow that could be better. This could be process changes such as versioning discipline, release types and schedules etc or UX changes such as better dialogs, better notifications, what's new information.

Having spent maybe 20 hours digging into how Vortex does what it does, here are my observations for the easiest wins with the smallest dev work.

Users don't like having updates downloaded and installed automatically

Currently, if the update is a patch (1.2.x), the update is automatically downloaded and then the user is notified to install and reinstall. This can feel invasive, they don't want to break their modding environments. They can't see the changelog (assuming they know what it is) either before or after

Proposed Changes

• Better version discipline by us so this mechanism is solely used for patches and not just for being lazy and needing to bump version. This will minimize how many times it's used, and if it is, it's for hot fixes and it's 100% needed for the greater good.
• Better UX by updating the text to say 'What's New' instead of 'Changelog' wherever it is mentioned. Explain what is happening and why.
• What's New to contain historic updates (5?) and not just the current release

Users want to know what the update is doing before agreeing to download and install

If the update is a minor (1.x.0), the user is warned that they can't go back after they've downloaded and installed this update. They can't see what is going to change and might not even know what a changelog is. The wording of notifications and dialogs are passive aggressive, lots of assumptions and factually incorrect.

Proposed Changes

• 'Update available' notification text changed to better explain what is going on
• Dialog to show What's New (instead of Changelog) that you download from there, and not just straight download from notification.
• What's New to contain historic updates (5?) and not just the current release

Users don't know they are on the beta update channel

The update beta channel is our only means of getting Vortex out to some people but not all. Users can choose this (or Stable or None) in the Settings and then Vortex will download beta versions as well as the stable ones as part of the normal updating flow. The problem is that users don't know what using beta software entails and if they are that precious about their modding environments, then they really should be waiting for stable versions. Vortex doesn't warn or give any information about what 'Beta' means, and so the misunderstanding is there because users just think it means exclusive and shiny, and not testing. We have the problem of people thinking everything is going to work perfectly.

Proposed Changes

• Version information in toolbar that is more prominent when Beta update channel, less so when Stable.
• Confirmation dialog explaining what switching to Beta (and a dialog for None) entails and what can be expected worse case. Channel will only switch from this dialog and not before.
• Notification on first load of this change that asks, if you are set to the Beta channel, what it means and do you want to continue. Same information as the dialog you'd now get if you choose beta.

There isn't any way to distribute builds that are pre-beta

Currently, we do a package and manually send that out to users or internally. It get's confusing as the GitHub Releases are used for the Changelog/What's New, and if it doesn't exist on GitHub, then it doesn't work the same and also updates aren't shown as you are technically ahead of what is known.

We don't want to go down a full update flow change of adding beta and alpha channels as there is too much backend work that will doing, testing, and a bit late in the project for that. There is further investigation needed so that the UX of a prerelease\alpha version makes more sense, is less janky and doesn't report incorrect versions as they are less than what we have.

Proposed Changes

• Go through the code areas where version matters and at the very least, put in some catches so it doesn't seem broken.

As a developer, I want to be able to test the update flow without using our main Vortex repo

When running in dev mode\non-packaged, our version is always reported as 0.0.1 and so the update flow can't be effectively tested. We have a Vortex-Next repo that can be used for it's release information instead of Vortex. This is accessed with the IS_PREVIEW_BUILD env variable but only effects the update repo and not the nexusmods.com staging API endpoints.

Proposed Changes

• Bring language in line with rest of company. Using alpha for any builds pre-beta and staging for a non-production environment.
• Change 'next' in Vortex to be 'alpha', so not to confuse with anything next.nexusmods.com related.
• Use env variables that makes sense such as USE_VORTEX_STAGING so that we can access Vortex-Staging repo, or using staging environments when accessing next.nexusmods.com.
• More clarification for this is needed as it's a bit janky but will help long term.

Other simple changes

• More disciplined use of GitHub release changelog formatting (as this is where Vortex get's it's information from) so we have a consistent html that Vortex can render correctly. No headings, only bullet points etc. Mike has suggested that bullet point only for changelog but have a clear language 'tldr' as an opening sentence/paragraph rounding up what this update is for. Minor releases only (1.x.0) as this is what the user will read before they click download.

Testing

• Rollbacks from beta to stable
• Dev mode notifications and updates and testing procedures

Todo

• Better version discipline by us so this mechanism is solely used for patches and not just for being lazy and needing to bump version. This will minimize how many times it's used, and if it is, it's for hot fixes and it's 100% needed for the greater good.
• Better UX by updating the text to say 'What's New' instead of 'Changelog' wherever it is mentioned. Explain what is happening and why.
• What's New to contain historic updates (5?) and not just the current release
• 'Update available' notification text changed to better explain what is going on
• Dialog to show What's New (instead of Changelog) that you download from there, and not just straight download from notification.
• Version information in toolbar that is more prominent when Beta update channel, less so when Stable.
• Confirmation dialog explaining what switching to Beta (and a dialog for None) entails and what can be expected worse case. Channel will only switch from this dialog and not before.
• More disciplined use of GitHub release changelog formatting (as this is where Vortex get's it's information from) so we have a consistent html that Vortex can render correctly. No headings, only bullet points etc. Mike has suggested that bullet point only for changelog but have a clear language 'tldr' as an opening sentence/paragraph rounding up what this update is for. Minor releases only (1.x.0) as this is what the user will read before they click download.
• Update confluence and docs with new procedures

Dialog texts from updating notifications and switching channels

Switching to Beta update channel

Development versions of Vortex can be unstable and cause irreparable damage to your modding environment.

We recommend using the Beta channel only if you are comfortable with the risks and are willing to report any issues you encounter. We don't recommend downgrading back from beta to stable.

Are you sure you want to switch to the Beta update channel?

Turning off updates

This will stop notifying you about new updates to Vortex.

This is not recommended as important security and stability updates are released regularly.

Are you sure you want to turn off updates?

Downgrade warning

Your installed version of Vortex (x.x.x) is newer than the one available online (x.x.x). This could of been caused by installing a pre release version and then swapping back to stable updates. This is not recommended and we suggest going back to the beta update channel.

Patch version downgrades (i.e. 1.9.13 downgrading to 1.9.12) are mostly harmless as Vortex's state information would have not changed extensively but Minor version changes (i.e. 1.10.x downgrading to 1.9.x) are usually significant and may alter your state beyond the previous versions capabilities. In some cases this can ruin your modding environment and require a new mods setup.

Are you sure you want to downgrade?