Change Alpha module versioning to support declaring version ranges

[humanzz]

Describe the feature

This is a request to change the versioning scheme for alpha modules to enable declaring version ranges to facilitate package updates.

Use Case

In my package.json, I declare the required CDK package versions using ranges to facilitate my later updates using commands like npm outdated and npm update --save (either manually or using automated tools e.g. Dependabot that do those updates).

For example, package.json would have entries like

"@aws-cdk/aws-glue-alpha": "^2.114.1-alpha.0",
"aws-cdk-lib": "^2.114.1",

and then running npm outdated, I'd get

Package                          Current           Wanted           Latest  Location
@aws-cdk/aws-glue-alpha  2.114.1-alpha.0  2.114.1-alpha.0  2.117.0-alpha.0  node_modules/@aws-cdk/aws-glue-alpha
aws-cdk-lib                      2.114.1          2.117.0          2.117.0  node_modules/aws-cdk-lib

Proposed Solution

I did come across a previous discussion about this in #15581 and it seems like the decision was made to use 2.x.y-alpha.z.

As I saw in the comments that the team considered this as a 2-way door, I'm opening this request, to maybe have a new discussion, now that those alpha packages have been out there in the wild for a while, and that there might be additional insights.

My proposed solution - for the simple version range declaration I wanted to do - is to use 2.x.y versioning scheme (even if they're not the same as aws-cdk-lib).

Other Information

No response

Acknowledgements

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

CDK version used

2.114.1

Environment details (OS name and version, etc.)

macOS

[pahud]

Yes it could be painful when we npm update.

Thank you for your feedback and we welcome more thoughts from the community.

[btd]

To add 5c to discussion. Current naming with -alpha.N sometimes breaking npm builtin mechanism to detect suitable version. We got this when used cdk-monitoring-constructs and some internal libs (CLE). If you specify peerDependency with -alpha module in several libs it breaks npm

[rix0rrr]

Hi @humanzz,

We can do this, but you are aware that we reserve the right to break -alpha APIs at any point, so an npm update can leave you with non-working code, right?

That's the entire purpose of alpha modules in the first place, so that's the contract you get. At least the versioning scheme we have now prevents accidental upgrades.

Yes, we could also bump major versions, but we have concerns that a large part of our audience might not entirely understand how CDK is at 2.x, but another "official" CDK package is at 3.x and yet another is at 15.x.

[humanzz]

@rix0rrr oh yes of course am aware of that.

I do have snapshot tests for my cdk app. So, the typical case I want to be able to do - for staying up to date

1. Update the dependencies using npm update
2. Build the app, to deal with any api changes (things that show up at Typescript build time)
3. Snapshot tests (and updating them as needed)

So, I do get alpha modules can introduce breaking changes - that's why they're not part of stable aws-cdk-lib. My sense is that given alpha is already part of the package name, and that documentation is clearly differentiating between the expectations of stable vs. alpha, that the alpha versioning scheme as it currently stands, does not provide much additional value.

[atipapp]

@rix0rrr One more addendum: dependabot doesn't allow pre-release version updates. So plus one for switching the versioning. See dependabot/dependabot-core#8161

[blimmer]

Linking this issue up with the new dependabot issue since this is still an issue.

• Old: All grouped dependencies not updated dependabot/dependabot-core#8161
• New: NPM alpha/prerelease dependencies don't update as expected dependabot/dependabot-core#10458

[blimmer]

+1 to reconsidering this. It's really painful when dealing with third-party constructs that rely on alpha packages. You're pretty much locked to a specific version of CDK because ^ ranges aren't allowed.

From the options originally posed in #15581 (comment), I'd love to see the 2.0.0-alpha.x or 0.x.y solution, which would allow semantic versioning to work properly.