RFC: 79 CDK v2.0 #156
RFC: 79 CDK v2.0 #156
Conversation
MrArnoldPalmer
requested review from
RomainMuller,
rix0rrr,
eladb,
NetaNir and
a team
Proposal detailing a new major version of aws-cdk. Lays out the plan for rolling out the release and continuity for support of current v1 modules. **Note** Lets talk about issues marked as "More info needed" to decide if they should be included or not. I didn't quite understand what they were or why they required incurring breaking changes. Related to: #79
MrArnoldPalmer
force-pushed
the
feature/cdk-2.0
branch
from
04ef431 to
e5da0d9
Compare
|
Title does not follow the guidelines of Conventional Commits. Please adjust title before merge. |
text/0079-cdk-2.0.md
Outdated
| ### v1 Deprecation | ||
|
|
||
| `@aws-cdk/` namespaced modules will continue to receive non-breaking changes and be released regularly. | ||
|
|
||
| When v1 module support is discontinued will ultimately be dictated by the introduction of some feature or change that the team agrees is worth the cost of dropping support and requires us to do so. Alternatively, if the burden of maintaining v1 module support is no longer warranted by the number of users continuing to rely on them. |
There was a problem hiding this comment.
I'm not convinced we're doing the right thing here.
dictated by the introduction of some feature or change that the team agrees is worth the cost of dropping support and requires us to do so
I'd rather us plan out when this happens, rather than pivot this on some feature/change that may or may not happen in the future. Besides not providing the appropriate messaging to our customers, there is the risk that this realization happens at the last minute and we'll scramble to execute on dropping support.
Not a nice experience for our customers or us.
if the burden of maintaining v1 module support is no longer warranted by the number of users continuing to rely on them
The way I'm reading this is - "not in any reasonable timeline". We've this happen with releases other in other tools or ecosystem (e.g., it took a long time python2.7 could be deprecated).
We should a take a different approach instead - define and announce a sunset period and/or a maintenance period for 1.0 and stop releases after that.
We should also consider an upgrade tool for customers to move from 1.0 to 2.0 (similar to the monocdk rewrite?) in all our supported languages.
Another benefit we will get from this is that deprecated code and packages can actually be deleted from our code base, and we'll no longer have to maintain backwards compat.
There was a problem hiding this comment.
I tend to agree and also becoming a bit concerned about our ability to actually hide deprecated APIs from v2.0 without really modifying the code. As part of #7708 and #7736 I ran into a few situations where stable APIs extend an experimental API (e.g. assets.IAsset). Apart from the fact that I think we should probably prohibit this, it will be impossible to hide IAsset even though it's marked deprecated. We have quite a few places like that in our code and I don't know how this will actually work.
An additional case is the constructs compatiblity layer, which will also require some actual code changes to get rid of.
I am leaning more and more towards a period of transitioning from a v1.0 code base to a v2.0 code base in which we can actually do some clean ups and leave the old stuff behind some how. This, naturally, will require us to plan better for this transition and be explicit about what we intend to backport. It also means that we may need to continue to release v1.x for a while from a branch.
There was a problem hiding this comment.
I'm leaning towards agreeing with both of you. I think we should agree on a period of continuing support for v1 modules and announce that up front. Additionally the cost of hiding deprecated APIs during build time appears to become more complex the more we look into it.
We could implement whatever we can with the v2 modules building from the v1 modules. Then we can branch the two, without creating a git branch, by copying all of the v1 modules src into the aws-cdk-lib modules src directory and change the way we are building to just build from those local copies. Then we can implement breaking changes in the aws-cdk-lib module and continue to release v1 as is. This lets us go back and add any critical updates to v1 modules, but obviously ends new features and minor bugfixes etc for v1 during the overlap period.
There was a problem hiding this comment.
I am concerned that duplicating the sources inside our repo and restructuring of our source repo will introduce risk and quite a lot of work into the critical path of v2.0. It will also require an awfully manual process to back port anything from 2.0 to 1.x and vice verse.
I would also consider a git branch as a mechanism to maintain these two version lines temporarily. Perhaps we can even do that at an early stage in order to break the version number: branch off to a 2.x branch today and have it continuously merge from master and build monocdk like today. Then, update the version number there to 2.x and create a separate pipeline that will release it.
Then, we can start applying changes and continue to merge from master until we officially release 2.x and perform the switch.
There was a problem hiding this comment.
Would something like this be feasible to keep it simple? Rather than trying to navigate a single branch driving two different release versions, we pick a date for the transition to a v2.0 release candidate, say the 'pre-release' date suggested above, and then on that date:
-
Create a v1.x branch of the repo. This will be the branch that the v1.x release(s) will be built from, and will only have security patches and important bugfixes backported into it. The v1.x releases of the CLI and Construct library are made off of the v1.x branch, and only the v1.x branch. This lets v1.x sticks around for a while for those that want to stay on it, but doesn't get any new features.
-
Mainline development shifts to a release-candidate process for v2.0. All new code targets the mainline branch. The CDK development team releases a new release candidate every N days/weeks, and when it looks stable enough for prime-time it does the official v2.0 release.
-
The reviewers for PRs on mainline would have to be cognizant of identifying changes that would need to be backported to the v1.x line, and there would have to be a process for that.
New v1.x releases are made as-needed, but their cadence should be drastically reduced as the vast majority of changes will be in mainline. We don't break any existing apps that are out in the world because the v1.x line has a clean break from the v2.0 line.
text/0079-cdk-2.0.md
Outdated
|
|
||
| #### [Deprecation Aware Builds]() | ||
|
|
||
| A strategy for selectively including or excluding apis marked `deprecated` during build time. This can be performed at the JSII level and potentially can be linked to specific version numbers with additional information in the `deprecated` annotation. JSII can warn when APIs marked for deprecation within a specific major version release are being included in the build. For example: |
There was a problem hiding this comment.
What about deprecated packages?
There was a problem hiding this comment.
Ideally we should omit them from the monocdk, but I think it might be impossible given we have some stable APIs that depend on deprecated/experimental APIs.
text/0079-cdk-2.0.md
Outdated
| An api annotated like so: | ||
| ```typescript | ||
| /** | ||
| * @deprecated-v1 |
There was a problem hiding this comment.
This feels more complicated than needed.
Why not just maintain only 2 active versions at any time? Before we move to the next major version, all items marked removed from the n-1 version is removed from source code.
There was a problem hiding this comment.
Thats what the design was meant to present. We would still want a # next to each deprecation to know if it was deprecated during the current, or previous cycle right?
text/0079-cdk-2.0.md
Outdated
| When inside a module versioned `1.x.x` | ||
| `jsii` - builds normally, no warning | ||
|
|
||
| when inside a module versioned `2.x.x` or greater | ||
| `jsii` - build fails with error stating that deprecated APIs are included and points to the corresponding lines of code. It will suggest usage of `--no-deprecations` option to exlcude these APIs. | ||
| `jsii --no-deprecations` - builds without warning, but excludes the above method and others marked deprecated during the v1.0 cycle |
There was a problem hiding this comment.
Sorry, I'm not following everything that is said here. Can you clarify better on the text here? It might read better if you start with the use case and then state the flags to use for that use case.
Are you saying that there is now an option to continue to keep deprecated APIs in the new version?
There was a problem hiding this comment.
No the --no-deprecations option is what you use when you want to remove deprecated APIs from the build you are performing. When you build without it, and JSII sees deprecated APIs from the current - 1 version cycle, it warns you saying that you are in fact including APIs that shouldn't be.
There was a problem hiding this comment.
Can we please add a detailed list of tasks that need to happen with issue links? Would be good to be able to go through this list and decide if we want to pick those up or not for v2.0
For example, the work to extract the custom resource code from s3-deployment (the AWS CLI) and publish to regional S3 buckets? Is this required before we release 2.0 or can this be done later?
text/0079-cdk-2.0.md
Outdated
|
|
||
| Since the CDK was announcned as "generally available", the team has tried to limit breaking changes for users. However, a handful of features have emerged that the core team believes will make the CDK significantly simpler to use. These changes require a 2.0 release to signal to users that code changes may be required for adoption. | ||
|
|
||
| The main change of note is to consolidate all of the aws service construct libraries into a single package. The motivation for this change is detailed in [the corresponding RFC](https://github.com/aws/aws-cdk-rfcs/issues/6). |
There was a problem hiding this comment.
| The main change of note is to consolidate all of the aws service construct libraries into a single package. The motivation for this change is detailed in [the corresponding RFC](https://github.com/aws/aws-cdk-rfcs/issues/6). | |
| The main change of note is to consolidate all of the aws service construct libraries into a single package. The motivation for this change is detailed in [the corresponding RFC](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0006-monolothic-packaging.md). |
text/0079-cdk-2.0.md
Outdated
|
|
||
| Since the CDK was announcned as "generally available", the team has tried to limit breaking changes for users. However, a handful of features have emerged that the core team believes will make the CDK significantly simpler to use. These changes require a 2.0 release to signal to users that code changes may be required for adoption. | ||
|
|
||
| The main change of note is to consolidate all of the aws service construct libraries into a single package. The motivation for this change is detailed in [the corresponding RFC](https://github.com/aws/aws-cdk-rfcs/issues/6). |
There was a problem hiding this comment.
| The main change of note is to consolidate all of the aws service construct libraries into a single package. The motivation for this change is detailed in [the corresponding RFC](https://github.com/aws/aws-cdk-rfcs/issues/6). | |
| The main change of note is to release the CDK as a single package instead of multiple packages. The motivation for this change is detailed in [the corresponding RFC](https://github.com/aws/aws-cdk-rfcs/issues/6). |
text/0079-cdk-2.0.md
Outdated
|
|
||
| ## Release Stages | ||
|
|
||
| CDK v2.0 will be released in stages. The stages also dictate if and how the v1 modules continue to be published. |
There was a problem hiding this comment.
Maybe provide an overview of the stages before diving into them to give readers the full picture upfront
text/0079-cdk-2.0.md
Outdated
| installing: `npm install aws-cdk-lib@beta` | ||
| package.json: | ||
| ```sh | ||
| "dependencies": { |
There was a problem hiding this comment.
Worth mentioning that this is for apps. Library vendors should use peerDependencies here, correct?
There was a problem hiding this comment.
Yeah I'll add a section for library authors here.
text/0079-cdk-2.0.md
Outdated
| "aws-cdk-lib": "~2.0.0-beta.1" | ||
| } | ||
| ``` | ||
| **Note: `~` ranges match all versions with the same major, minor, and patch numbers with a greater prerelease number. For example, the above would match `2.0.0-beta.2`. but not `2.0.1-beta.2`.** |
There was a problem hiding this comment.
Will it also match 2.1.1-beta.2?
There was a problem hiding this comment.
What's our strategy for bumping these numbers? I am wondering if perhaps the last number should reflect the major+minor of the corresponding 1.x?
Can we do something like this:
| v1 | maps to v2 |
|---|---|
| 1.32.0 | 2.0.0-beta.32.0 |
| 1.33.2 | 2.0.0-beta.33.2 |
There was a problem hiding this comment.
it wont match 2.1.1-beta.2. It only matches pre-releases with the same major, minor, and patch with a newer prelease tag. So it has to be 2.0.0-beta.x.
We will have to test if we can version this way, matching the numbers of the pre-release tag to the minor.patch numbers of the current v1 release. I agree that would be ideal but looking through npm semver docs I don't see examples of additional numbers beyond the -beta.x.
There was a problem hiding this comment.
Spec says it's okay: https://semver.org/#spec-item-9
text/0079-cdk-2.0.md
Outdated
|
|
||
| Since `aws-cdk-lib` will have a version number differing from the one used by lerna to version all of the other packages in the repo until the "stable" phase, changes to the align-version and bump scripts will have to be made in the repo to handle this. | ||
|
|
||
| #### [Deprecation Aware Builds]() |
There was a problem hiding this comment.
I wonder if this is worth a separate RFC or at least a deeper dive/prototype.
There was a problem hiding this comment.
I think a prototype is whats needed.
text/0079-cdk-2.0.md
Outdated
|
|
||
| ## Rationale | ||
|
|
||
| The main motivation for moving forward with a 2.0 release now is the desire to start moving towards the single module structure. The current multi module structure is known to cause a lot of confusion for users. For more details on why aws-cdk is moving to a single package, see the [MonoCDK RFC](https://github.com/aws/aws-cdk-rfcs/issues/6). |
There was a problem hiding this comment.
It's not only user confusion or a "belief" that this is better. It's basically impossible to use CDK modules as peer dependencies since every transitive dependency change will be breaking.
There was a problem hiding this comment.
Will rethink the wording here. Mostly just trying to say "go read the mono rfc".
text/0079-cdk-2.0.md
Outdated
| All users will perform the following to adopt cdk v2 | ||
|
|
||
| 1. Update Dependencies - Changing from referencing the old `@aws-cdk/` packages to the new `aws-cdk-lib` package in the corresponding target language's package manifest (package.json, .sln, pom.xml, setup.py). | ||
| 2. Update Imports - Since the current module structure is being changed, import statements in user's code will need to change to accommodate the change. This will be automated with the [import rewriter](#import-rewriter). |
There was a problem hiding this comment.
Hopefully not in all languages
text/0079-cdk-2.0.md
Outdated
| 1. What additional features beyond adding the necessary tooling for releasing a major version going forward, should be included if any? | ||
| 2. As part of jsii submodule support, can namespace renaming mitigate the need for users of non-typescript target languages to restructure their import statements? | ||
| 3. Can `experimental` APIs be separated at build time to make their usage more explicitly "opt-in" for users? | ||
| 4. With regards to automatic exclusion of deprecated APIs, more discovery will be needed to converge on a specific technical strategy. It is currently thought this can be achieved by excluding classes/methods marked `deprecated` during JSII code generation. However, since the typescript/javascript packages are emitted by the typescript compiler, it will have to be done differently for the typscript language target. The current idea is to hide the deprecated APIs by removing their types from the `.d.ts` files emitted during build. |
There was a problem hiding this comment.
/@deprecated/@internal/g before compilation might do the trick
There was a problem hiding this comment.
I'd like to see a table of the union of all packages at v1 and v2 (fold the service modules into one, not a lot of value in the additional noise there), whether or not they'd go into the monoCDK, and what the names would be before and after the switch.
Just to get some clarity and make sure we haven't overlooked any oddball packages.
text/0079-cdk-2.0.md
Outdated
| CDK 2.0 consists of the following notable changes: | ||
|
|
||
| - [Monolithic Packaging](https://github.com/aws/aws-cdk-rfcs/issues/6) - Combine all aws construct libraries into a single package. | ||
| - [Reset all Feature Flags](https://github.com/aws/aws-cdk-rfcs/issues/55) - Delete all defined feature flags and extraneous logic for the "old" state. |
There was a problem hiding this comment.
We're going to have a hard time doing this if we plan to release the same code under 2 versions, methinks? Do you have a strategy for this?
text/0079-cdk-2.0.md
Outdated
|
|
||
| *Importing experimental constructs from aws-cdk 2.0* | ||
| ```typescript | ||
| import {aws_appsync as appsync_experimental} from 'aws-cdk-lib/experimental' |
There was a problem hiding this comment.
Very curious to see how this is going to work for JSII languages...
text/0079-cdk-2.0.md
Outdated
| "aws-cdk-lib": "~2.0.0-beta.1" | ||
| } | ||
| ``` | ||
| **Note: `~` ranges match all versions with the same major, minor, and patch numbers with a greater prerelease number. For example, the above would match `2.0.0-beta.2`. but not `2.0.1-beta.2`.** |
There was a problem hiding this comment.
Spec says it's okay: https://semver.org/#spec-item-9
text/0079-cdk-2.0.md
Outdated
|
|
||
| ### Stable | ||
|
|
||
| After a period of testing and gathering feedback from users, `aws-cdk-lib` will be promoted to a stable release with the version `2.0.0`. All other modules, excluding those under the `@aws-cdk/` namespace, will also get promoted to v2.0, though will remain backwards compatible with `@aws-cdk/` modules. |
There was a problem hiding this comment.
All other modules, [...] will also get promoted to v2.0, though will remain backwards compatible with
@aws-cdk/modules.
I would like to see a table with a list of modules (collapsing all the service packages into one), and what treatment they'll be getting. I'm afraid a couple of these things won't be like the others.
text/0079-cdk-2.0.md
Outdated
|
|
||
| - [Public S3 Artifacts](https://github.com/aws/aws-cdk-rfcs/issues/39) | ||
|
|
||
| A significant downside of packaging all of the aws service construct libraries together is that the size of dependencies shipped to the users in most cases will be increased significantly. Being able to remove assets, like custom resource lambda code, that are currently bundled with the modules, could mitigate some of the impact on package size. This could be accomplished by packaging said assets, uploading them to S3, and then creating publically accessible lambda function layers referencing them across all AWS regions. Whether v2 of the cdk could accomplish this without impacting v1 has not been determined. |
There was a problem hiding this comment.
It would be quite scary to me to have this maintenance burden of a set of public artifacts.
All of a sudden we'd be responsible for replicating these all across the world, have monitoring on them, have backups, have a release pipeline, ...
text/0079-cdk-2.0.md
Outdated
|
|
||
| - [Rename ID Parameter](https://github.com/aws/aws-cdk/issues/3203) | ||
|
|
||
| `id` is a reserved keyword in python. Renaming this parameter in constructs prevents possible errors. This likely could be implemented as a feature flag with the flag removed as part of the normal major version release process. |
There was a problem hiding this comment.
It's not a reserved keyword though, it's a built-in function. It might be a valid concern, but I find the linked ticket light on details and full of FUD.
I think this could lead to potentials errors down the line for users that use the Python variant of CDK, since the id parameter could clash with the id() function.
Potential confusion how? What is the code he sees people typing that is wrong?
What's more likely is that his editor is yellow-underlining this id variable and saying "you shouldn't do this".
That's fair enough, and might be a good enough reason to change it for that alone, but let's be accurate about why we're doing it: "prevent IDE linter warning on all constructs" is a lot sharper and easier to reason about than "something might go wrong somewhere".
text/0079-cdk-2.0.md
Outdated
|
|
||
| `id` is a reserved keyword in python. Renaming this parameter in constructs prevents possible errors. This likely could be implemented as a feature flag with the flag removed as part of the normal major version release process. | ||
|
|
||
| #### Not Recommended |
There was a problem hiding this comment.
Agreed on all counts. This is going to be hard enough already, let's not make it worse than necessary.
text/0079-cdk-2.0.md
Outdated
|
|
||
| The main motivation for moving forward with a 2.0 release now is the desire to start moving towards the single module structure. The current multi module structure is known to cause a lot of confusion for users. For more details on why aws-cdk is moving to a single package, see the [MonoCDK RFC](https://github.com/aws/aws-cdk-rfcs/issues/6). | ||
|
|
||
| This belief that releasing a single package will make user's lives easier is countered by a strong desire to limit the exposure of users to breaking changes. Though the aws-cdk is relatively young, one of the core tenants of the project is stability. Major version upgrades are an important part of building and maintaining libraries. However, limiting the cost of breaking changes included in major releases is important. It isn't in the interest of the project to drop a new major version, immediately stop supporting the previous version, and leave the onus on the user to "catch up". |
There was a problem hiding this comment.
| This belief that releasing a single package will make user's lives easier is countered by a strong desire to limit the exposure of users to breaking changes. Though the aws-cdk is relatively young, one of the core tenants of the project is stability. Major version upgrades are an important part of building and maintaining libraries. However, limiting the cost of breaking changes included in major releases is important. It isn't in the interest of the project to drop a new major version, immediately stop supporting the previous version, and leave the onus on the user to "catch up". | |
| This belief that releasing a single package will make user's lives easier is countered by a strong desire to limit the exposure of users to breaking changes. Though the aws-cdk is relatively young, one of the core tenets of the project is stability. Major version upgrades are an important part of building and maintaining libraries. However, limiting the cost of breaking changes included in major releases is important. It isn't in the interest of the project to drop a new major version, immediately stop supporting the previous version, and leave the onus on the user to "catch up". |
text/0079-cdk-2.0.md
Outdated
| The cost of migration for users varies depending on the state of the application being migrated. All users upgrading to v2 will have to perform the following steps: | ||
|
|
||
| 1. Update Dependencies - Changing from referencing the old `@aws-cdk/` packages to the new `aws-cdk-lib` package in the corresponding target language's package manifest (package.json, .sln, pom.xml, setup.py). | ||
| 2. Update Imports - Since the current module structure is being changed, import statements in user's code will need to change to accommodate the new structure. This will be automated wherever needed with the [import rewriter](#import-rewriter). |
There was a problem hiding this comment.
Just a niggle, but an automatic rewriter is not guaranteed to work in the presence of removing deprecated APIs.
If you were using deprecated stuff, it's gone now. No way to rewrite around that.
|
The team has discussed further decoupling of the |
|
I'd actually like for V2 to also be coordinated with the removal of all type union usage everywhere. |
@RomainMuller Please add to #79 |
|
Reopening this as we get ready to revise. The biggest change is that we are no longer trying to publish both 1.0 and 2.0 modules from the main branch and instead will branch off for 2.0 for some short time, then merge back when it is ready to publish. Some questions that arise with that.
|
|
@RomainMuller something that we should include as part of the LTS model for vPREV (v1.x) is a mechanism to track usage of each version during the transitional period. Perhaps the LTS model will have stages based on % of customers using the old version. I think this data will be critical to track users' migration to v2.x and announcing EOL for v1.x. |
|
Here are 2 concerns I have with the current proposal, and ways to address them.
Working on forks is going to be hellIf we are going to be working on 2 completely separate codebases, especially if we're going to have a period where there is a "free-for-all, make all the breaking changes you want", our code is going to diverge and applying fixes and features to both of them is going to be a nightmare. I'm not looking forward to this world. I'd prefer a more mechanical approach, where we vend both v1 and v2 from the same branch, and the only changes between them are automated in a mechanical way, and revolve around packaging.
We'll only ever master 2 releases at the same time in the same branch. When we finally switch to v3, the now actually ACTUALLY deprecated code from v1 can finally and safely be removed from the code base. This will have the advantage that we'll be able to support v1 for longer, and it also has the advantage that there's only one branch to work on, so no merge conflicts. There is a downside in that there are some kind of breaking changes we can not make cutting over from v1 -> v2. For example, we cannot repurpose classes or properties (for example the Maybe we can even do some more automated tricks, like this: /**
* An AutoScalingGroup
*
* @rename v1 RealAutoScalingGroup
*/
class AutoScalingGroup { Or something. Incompatible changes is going to prevent people from upgradingThe worst thing we can do is make it hard for people to upgrade. If there's even the littlest thing that will break for them in their current deployments that doesn't have an escape hatch/way out, then they will not upgrade, and stick happily to v1, and our ecosystem will fracture. I'm not talking about code changes--code is stateless and easy to change. The deployments that are already out there are another matter. Those exist, have been created with some configuration, and have to be maintained with that configuration. That means that every flag and bit we flip by default for v2 should be unflippable, and we can't make any changes that impact the layout of deployments that aren't undoable by a flag. |
|
@rix0rrr gets my vote! |
Co-authored-by: Elad Ben-Israel <benisrae@amazon.com>
Co-authored-by: Elad Ben-Israel <benisrae@amazon.com>
|
|
||
| - features dedicated to facilitating migration from `v1` to `v2` | ||
| - features back-ported from `v2` | ||
| - bug fixes (where relevant, the author is expected to submit the `v2` fix at the same time) |
There was a problem hiding this comment.
| - bug fixes (where relevant, the author is expected to submit the `v2` fix at the same time) | |
| - `P0` bug fixes (where relevant, the author is expected to submit the `v2` fix at the same time) |
Is this correct (based on the above paragraph)? We will only accept P0 bugs on v1, so we'll only accept PRs for P0 bug fixes?
There was a problem hiding this comment.
No - I think we should accept bug fixes from the community for any severity, but we (the core team) will not author them.
Co-authored-by: Nick Lynch <nlynch@amazon.com>
Co-authored-by: Nick Lynch <nlynch@amazon.com>
Co-authored-by: Nick Lynch <nlynch@amazon.com>
|
Title does not follow the guidelines of Conventional Commits. Please adjust title before merge. |
| | 🚫 Out | [#39] | Distribute lambda code for bundled custom resources via a public S3 bucket | | ||
| | 🚫 Out | [RFC-77] | Generate CloudFormation Resources from the CloudFormation Registry schemas | | ||
| | 🚫 Out | [RFC-193] | Fix API for TypeScript type unions when used in statically typed languages | | ||
| | 🚫 Out | [#116] | Easier identification of `@experimental` modules and APIs | |
There was a problem hiding this comment.
What is the plan for "experimental" constructs in CDK v2.0? Too many customers have come to the wrong conclusion about the stability of the CDK because they were using experimental modules and didn't know it; presumably because they didn't read the API reference labels. The note above this table states the solution is "likely" achievable without breaking customers, but how we solve this particular problem is not stated. I like the proposal in issue #116 to have 2 versions of the CDK; e.g. aws-cdk-lib (stable constructs only) and aws-cdk-lib-experimental (stable + experimental constructs). I think the best way to avoid this confusion going forward is to require customers to intentionally import a package that clearly says it's experimental.
There was a problem hiding this comment.
The non-breaking thing we can do here quickly is add "(experimental)" to the front of every experimental API's docstring.
Two different libs won't work well as soon as we involve 3rd party libraries.
| were previously simply _neutralized_ in `v2` so that they could no longer be disabled there). | ||
|
|
||
| ## Monitoring Adoption | ||
|
|
There was a problem hiding this comment.
I don't think there is much work to do on the CDK CLI side of our metrics collection, but we'll need to rethink how we use the AWS::CDK::Metadata resource to track usage since all CDK constructs will be delivered in a single package/module. Ideally, we'll get more granular data on the actual constructs (L1, L2, or L3) used in CDK code.
| # Adoption Strategy | ||
|
|
||
| All users will perform the following to adopt CDK v2 | ||
|
|
There was a problem hiding this comment.
What's the feasibility of a migration tool to help customers update their dependencies and imports?
There was a problem hiding this comment.
All of this is easy if you consider one language (TypeScript/Javascript). Things become much hairier once you start to think about Python, C#, Java, ... I think if we go into tooling we should put ourselves in the position to offer an equally managed experience for all languages (and I don't think this is realistic).
RFC: #79 CDK v2.0
Rendered version
Proposal detailing a new major version of aws-cdk. Lays out the plan for
rolling out the release and continuity for support of current v1
modules.
Note Lets talk about issues marked as "More info needed" to decide
if they should be included or not. I didn't quite understand what they
were or why they required incurring breaking changes.
Related to: #79
By submitting this pull request, I confirm that my contribution is made under
the terms of the Apache-2.0 license