Description

Today, the upgrade notice is fairly simple:

In my opinion, there are a few things that could be improved with this message:

1. If the user is using TypeScript the provided command (npm i -g aws-cdk) isn't quite accurate. These users should instead use something like npm-check-updates to update the version pinned by their package.json and lockfile to upgrade CDK. If you run the command provided, you'd end up with a mismatch between your local version and the version specified in your project.
2. If a user is using 1.x, it would be nice to link to the Migrating to AWS CDK v2 documentation. This will give people an idea of what it entails to tackle the major upgrade.
3. During the 1.x to 2.x migration, it would be nice to provide additional information about maintenance, as specified in this RFC. The current implementation only shows that a new major version is available so, as a user, I might not be aware that I can safely use 1.x for another 6 months in "maintenance mode" as described by the RFC.

Use Case

As a CDK user, I want to understand what the upgrade process entails. It's an investment to keep up-to-date, especially with a fast-moving project like aws-cdk.

Also, as someone who uses aws-cdk regularly, I want to make it easier for folks who are casual users to understand the upgrade process.

Proposed Solution

Here are some ideas for each of the ordered list above:

1. More accurate upgrade information. I propose that a new section(s) is added to the AWS CDK documentation guide that explicitly describes how to upgrade aws-cdk for each supported language. I believe the process only differs between TypeScript and "everything else". For TypeScript, I believe users should be installing a pinned version of the aws-cli in their package.json and lockfile. So, to upgrade, they should update their versions in a project-specific (e.g., not global) way. For everyone else, they should upgrade via their installation path (e.g. homebrew, npm global install, etc.).
2. 1.x -> 2.x Upgrade Info. This shouldn't be too bad to add. I'll take a stab at a PR for this.
3. Exposing Maintenance Info. There are a few ways we could go about this. If there's a "hard and fast" window per major-version we could expose, I think that would be the best-case scenario. For instance, if we know that 1.x will be EOL-ed in June 2022, let's expose that right in the upgrade message (e.g., "You're using 1.x.x, which will no longer be supported as of June 2022. Please upgrade to 2.x before then to stay on a supported version."). Does this seem reasonable? If so, we could add something like this. Otherwise, we could link to the RFC about maintenance, but that's not as actionable as providing a date in my opinion.

Other information

No response

Acknowledge

• I may be able to implement this feature request
• This feature might incur a breaking change