(aws_cdk): removal of core package makes upgrading to v2 hard

[rittneje]

General Issue

The aws_cdk.core package was removed in v2, with no smooth migration path.

The Question

This is an experience report about the transition from v1 to v2.

In v1, the core package contains lots of highly used classes, such as core.Stack, core.Construct, and core.Duration. References to this package are peppered throughout our code base, especially our shared code.

In v2, the core package is completely gone. Most of the classes moved to aws_cdk.

This makes it impossible to upgrade from v1 to v2 smoothly. We cannot switch everything to aws_cdk beforehand, because that package doesn't exist in v1. And we cannot wait until after the upgrade to switch everything over piecemeal, because the core package doesn't exist in v2. This means we have to fix all the imports en masse at the same time as the v2 upgrade, which is extremely difficult for a repo that is under active development. Also, any code that is shared across repos that are on different major versions of cdk will break one way or another.

As a workaround, we basically have to patch v2 to pretend that the core module still exists, which is very cumbersome. This situation really should have been considered when you were designing out v2. There MUST always be a smooth migration path from version A to version B of CDK. It is not acceptable to mandate we make all changes at once.

CDK CLI Version

1.140.0 -> 2.15.0

Framework Version

No response

Node.js Version

No response

OS

No response

Language

Python

Language Version

3.9.10

Other information

No response

[peterwoodworth]

Was your team able to make use of our migration guide?

We appreciate the feedback, but I'm honestly not sure exactly what was tricky about the migration process for you. I'm not sure how patching v2 to pretend that the core module still exists could ever be easier than switching names of imports around if I'm being honest. Can you elaborate on this please?

Additionally, it's a major version upgrade. By definition, major version upgrades are where lots of things like this will change. Not sure when we'd make major changes to our product if not for then 🤷🏻

[rittneje]

I'm not sure how patching v2 to pretend that the core module still exists could ever be easier than switching names of imports around if I'm being honest.

@peterwoodworth When a code base is under active development, changing all the imports in one go is absolutely not trivial. Other developers are simultaneously adding new files (which reference the core package), while we are in the middle of changing all the existing ones. It is not acceptable to have a code freeze while we do this.

Additionally, it's a major version upgrade. By definition, major version upgrades are where lots of things like this will change. Not sure when we'd make major changes to our product if not for then

I suggest you look at Kubernetes for an example of breaking changes done properly. In one release, you would have both aws_cdk and core side-by-side. Then in a second release, you would only have aws_cdk. When people are upgrading, they stop at that interim release, fix all the imports, and then proceed to the final release.

[peterwoodworth]

Thanks for the feedback, this all makes sense to me.

@rix0rrr pinging for visibility

[github-actions[bot]]

Hello! Reopening this discussion to make it searchable.