Finalize the versions of the unstable modules in V2

Two main questions:

1. Should they be versioned independently of each other, or should they all be released in a single version together, like V1 modules are today?
2. What should be the exact version - 2.0.0-<prerelease-tag>, or 0.x.y?

This issue might also weigh in on that decision.

[njlynch]

(Summarizing some more offline conversations):

I don’t recall the specific reasons why the 2.x.y-alpha.z convention was deemed too confusing. I think it needs to be re-evaluated. Briefly, I believe these are the trade-offs for each:

2.0.0-alpha.x: Publish each package with a 2.0.0-alpha.x version, bumping x on every release.

• Makes it clear the package belongs with CDK version 2. ✅
• Clearly decouples the alpha packages from aws-cdk-lib (no confusion about the versions needing to be in sync) ✅
• No versioning semantics (no distinction between minor update and breaking change) ❌
• Requires per-package versioning ❌
  • More complex implementation
  • Per-package CHANGELOG (can’t aggregate to a single version; requires additional infrastructure to publish separate CHANGELOGs).
  • Requires docs architecture changes to expose the individual package versions

2.x.y-alpha: Publish all packages with a 2.x.y-alpha version, where x and y follow the current aws-cdk-lib version.

• Makes it clear the package belongs with CDK version 2. ✅
• May lead to misconception that alpha package versions must be aligned with aws-cdk-lib versions ❌
• No versioning semantics (no distinction between minor update and breaking change) ❌
• Simplest implementation by far (no per-package versions, changelogs, and docs). ✅

0.x.y: Publish each package with a 0.x.y version, bumping x on breaking changes and y on minor changes.

• No clear tie to CDKv2 (vs v1 or future v3). ❌
• Clearly decouples the alpha packages from aws-cdk-lib (no confusion about the versions needing to be in sync) ✅
• Versioning semantics - allows customers to only take in non-breaking changes ✅
• Requires per-package versioning ❌
  • More complex implementation
  • Per-package CHANGELOG (can’t aggregate to a single version; requires additional infrastructure to publish separate CHANGELOGs).
  • Requires docs architecture changes to expose the individual package versions

---

Given the above, I continue to believe that the 0.x.y strategy – combined with a potential package naming change to make the v2 tie-in clearer – is the best solution. However, it’s also prohibitively expensive, with a back-of-the-envelope cost of somewhere around 4x the work of the 2.x.y-alpha solution. Given that cost – combined with the scope-creep that has been a hallmark of the V2 release – the 2.x.y-alpha solution strikes me as the best compromise. I also believe there is a 2-way door here; we can absolutely pivot our alpha versioning strategy in the future if necessary, especially as new alpha modules are created and old ones graduated to stable.

Going to post this around for final comments period. Please vote via the following reactions:

VOTING RUBRIC: 👀 - 2.0.0-alpha.x 👍 - 2.x.y-alpha 🚀 - 0.x.y

[github-actions[bot]]

⚠️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.