Which packages are compatible with others?

Feature request

Is your feature request related to a problem? Please describe.

There have been a few issues hit by the community because it’s not clear which versions of the packages are compatible with each other. For example: https://github.com/keystonejs/keystone/issues/2588

Describe the solution you’d like

I think there are two ways to solve this problem:

1. Do what Gatsby does. Every package in their monorepo is versioned together, so as a user all you need to do is ensure all your keystone packages are the same version, and you know they’ll work together. If a package isn’t changed in a release, it still gets its version bumped so you can just treat Gatsby as all having the same version number.
2. Publish a compatibility matrix of every version of every package and what other package versions are compatible. Implement checks in each package to make sure the other packages are compatible on start up.

Describe alternatives you’ve considered

Stab in the dark with various versions until you get something that appears to work, but may be broken in subtle ways because of incompatibilities. (Seems less than ideal to me.)

Additional context

To be production ready, we really need to know what’s compatible with what.

• Can I use @keystonejs/app-admin-ui version 5.9.1 with @keystonejs/keystone version 6.0.2?
• What about @keystonejs/app-admin-ui version 5.9.1 with @keystonejs/keystone version 7.0.0?

How can I check that these combinations are compatible or not compatible?

[thekevinbrown]

@Noviny that makes sense, thanks.

I think the most confusing thing about the approach you’re proposing is it kind of misses the point of semver to me. If all of these were definitely separate things that work separately, then sure, they each version separately. But very few people in the world are going to be using one of these without stringing them together. Here’s what’s in my package.json:

"@keystonejs/adapter-knex": "6.2.0",
"@keystonejs/app-admin-ui": "5.7.2",
"@keystonejs/app-graphql": "5.0.3",
"@keystonejs/auth-password": "5.0.2",
"@keystonejs/fields": "6.2.2",
"@keystonejs/keystone": "5.4.3",

Does fields 6.2.2 work with keystone 5.4.3? What about adapter-knex v6 with admin-ui 5.7.2? It’s confusing to have Keystone be behind the packages it’s using that had breaking changes but still work with it. To me it feels dogmatic to stick to, “Keystone hasn’t had a breaking change, so it doesn’t move, but fields has, so it does” because it doesn’t actually help consumers understand what the breaking change is. Do I need to change my code? What are we signalling with that version change that someone external to the package needs to know? This approach feels to me like a history lesson as opposed to useful information for me as a consumer.

Also, over time if this drift continues we’re going to be looking at something like fields v24 being compatible with keystone v11, and that’s completely unhelpful from my perspective. What does it help me to know that there have been 24 breaking changes in fields, and 11 in Keystone? That’s a history lesson. I want to know if the packages I’m using work together, not the history of how we got here, and on each release I want to know if I can safely incorporate that release without breaking my setup. From my current package.json, the answer from the versioning is “maybe”, which to my mind defeats the purpose of using semver in the first place. I should know what’s safe to incorporate from the version number, or semver isn’t helping me. That’s what semver is for.

I’d propose that a compromise here would be:

• Arch UI is a separate thing, because it actually is in terms of how it’s published already.
• When you have a major version bump in any @keystone package you major bump and publish all of the packages so they don’t drift so far apart as to be confusing. The minor and patch bumps can drift all they like within the majors, but as a consumer I know what the boundaries are when consuming updates of the various packages.

From my perspective that solves all of the major concerns both of us have and actually makes the semver more meaningful and useful to consumers than it is currently.

---

TL;DR: I should know what’s safe to incorporate from the version number, or semver isn’t helping me. That’s what semver is for.

[emmatown]

Given that most things are now in the @keystone-next/keystone package and the other packages have a peer dependency on @keystone-next/keystone making it clear what version of @keystone-next/keystone it needs, I think this is now addressed.