(cli): improve upgrade banner message

[blimmer]

Description

Today, the upgrade notice is fairly simple:

aws-cdk/packages/aws-cdk/lib/version.ts

Lines 109 to 112 in 0745193

	const bannerMsg = formatAsBanner([
	`Newer version of CDK is available [${colors.green(laterVersion as string)}]`,
	'Upgrade recommended (npm install -g aws-cdk)',
	]);

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

[blimmer]

I spent a bit of time today attempting to implement the upgrade message improvement (see https://github.com/aws/aws-cdk/compare/master...blimmer:blimmer/improve-upgrade-message?expand=1).

I'm running into some problems with testing that I'll need to spend some more time on, though. Feedback welcome for folks who might be more familiar with the sinon/jest setup in cdk.

[rix0rrr]

Feel free to turn this into a PR, I can have a better response when I can see the error messages.

[github-actions]

This issue has not received a response in a while. If you want to keep this issue open, please leave a comment below and auto-close will be canceled.

[blimmer]

@rix0rrr, I got the testing issue figured out. #18195 handles item "2" from the list. Items 1 & 3 still need a bit of consideration and discussion, I think.

[rix0rrr]

Thanks for the PR.

I think item 1 would be covered by https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html#migrating-v2-v1-uppgrade

Item 3 will be addressed by aws/aws-cdk-rfcs#389

I think everything here is addressed, will be closing this issue. Please let me know directly if there's something I missed.

[github-actions]

⚠️COMMENT VISIBILITY WARNING⚠️

Comments on closed issues are hard for our team to see.
If you need more assistance, please either tag a team member or open a new issue that references this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.