st2 pack install should check existing installed version and warn if new version being installed is incompatible

[lakshmi-kannan]

This came from AWS pack discussion where we will have two branches boto2 and boto3. master branch will point to boto2 for now. When we deprecate boto2 and make boto3 the default, master will point to boto3.

If user already has boto2 aws installed and does st2 pack install aws when master points to boto3, we'd mess up the user box. We should detect the version of aws pack installed and check if incoming version is incompatible.

[LindsayHill]

How will you know that new version is incompatible? What will it be incompatible with?

[dzimine]

Installing the most recent version is a reasonable default.

A user can specify & pin the version of the pack (given the discipline of pack authors on versioning):

st2 pack install cloudflare=0.1.0

see https://docs.stackstorm.com/packs.html

Compatibility and upgrade notes are pack author responsibility IMO.
The recovery from messed up pack is easy, too: remove the pack, re-install with version specified.

So to me, it's "no-op".

The one little thing to reduce "user error" may be to require a flag to "upgrade if exists", and error out if flag not specified.

[Mierdin]

The new version of the AWS pack will introduce some breaking changes, and we were discussing ways to make that more obvious. I think there's a reasonable expectation that users will read upgrade notes when upgrading st2 core, but this is far less emphasized for packs. So for popular packs like the AWS pack, when breaking changes are introduced, this could be as disruptive as breaking changes in st2 itself.

So this would go beyond users pinning versions - we would want to add some form of metadata to the pack config that indicates a "boundary" between incompatible versions, so that the user can be properly notified. To answer @LindsayHill question, we would want to query the DB first to see what version is already installed, and figure out from the pack meta if that version is incompatible with the new version attempting to install. This would require a code change for sure, the net benefit is that we have a bit more to offer the user in the form of warnings when they're about to introduce something disruptive by re-installing a pack, instead of just assuming they'll read the upgrade notes

[LindsayHill]

We've had quite a few breaking changes in configs in the past, but it hasn't been handled well. Has relied on users reading CHANGELOG, if it even exists.

In terms of breaking changes, I guess there's three categories:

1. Pack configuration change.
2. Action behavior change - e.g. changes to required parameters, or format.
3. Actions changing name, which would break workflows relying on those changes.

The problem is: How do you identify those in a programmatic way? How do you decide from pack metadata that the new version is incompatible with the old ones? Gets messy if you try to maintain some complex schema of compatible versions.

Maybe instead we enforce semver for any pack.yaml version changes, and require major version change for anything breaking. Then st2 pack install can check: is new version a major version above currently installed, if so: give some warning message. Provide user ability to force pack install without checks/warning message.

Will that work?

[warrenvw]

@LindsayHill I personally like the idea using pack.yaml version. Simple. Effective.

[Mierdin]

I like the semver solution, though it would require a bit more handholding for all existing packs so people don't bump major versions willy-nilly. This would go above simply enforcing semver, which is easy to do, but also ensuring that changes to the version are meaningful (telling pack maintainers that fixing a typo doesn't qualify as a major change).