From e5da0d986cadc507fca4877680acf2ac7b8c8584 Mon Sep 17 00:00:00 2001 From: Mitchell Valine Date: Thu, 30 Apr 2020 22:40:47 -0700 Subject: [PATCH 01/21] RFC: 0079 CDK v2.0 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 --- text/0079-cdk-2.0.md | 337 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 337 insertions(+) create mode 100644 text/0079-cdk-2.0.md diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md new file mode 100644 index 000000000..3de932ba7 --- /dev/null +++ b/text/0079-cdk-2.0.md @@ -0,0 +1,337 @@ +--- +feature name: cdk-2.0 +start date: 2020-3-29 +rfc pr: https://github.com/aws/aws-cdk-rfcs/pull/156 +related issue: https://github.com/aws/aws-cdk-rfcs/issues/6 +--- + + +# Summary + +CDK v2.0! + +This RFC details the strategy for building and releasing aws-cdk 2.0, in addition to changes to tooling required to support this strategy. For details on the specific features themselves, see the corresponding RFCs. + +# Motivation + +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). + +The core motivation of this proposal is to detail the plan required to release this change while continuing to support users referencing the v1 modules. In short, we want to make sure users have plenty of time to transition their code to using the new module structure and make that transition as easy as possible. + +# Basic Example + +### New Module Structure + +*Installing aws-cdk 2.0* +```bash +npm install aws-cdk aws-cdk-lib +``` + +*Importing modules from aws-cdk 2.0* +```typescript +import { + aws_ecs as ecs, + aws_lambda as lambda, + aws_s3 as s3, +} from 'aws-cdk-lib'; +``` + +*Importing experimental constructs from aws-cdk 2.0* +```typescript +import {aws_appsync as appsync_experimental} from 'aws-cdk-lib/experimental' +``` + +# Design Summary + +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. +- Remove Deprecated APIs - Delete all constructs/methods marked with `@deprecated` flag. +- Separate Experimental Code - Extract experimental APIs into a separate entrypoint. + +# Detailed Design + +## Release Stages + +CDK v2.0 will be released in stages. The stages also dictate if and how the v1 modules continue to be published. + +### 1. Experimental + +A module under the name `monocdk-experiment` is created that re-exports the contents of all of the `@aws-cdk/` namespaced modules. The version number of `monocdk-experiment` is locked to the version of all other modules in the monorepo. + +`monodk-experiment` has no source code of its own. It is a series of build scripts that creates a module that re-exports all of the code of `@aws-cdk/` packages. The build step peforms these actions: + +1. Build and validate package.json - This verifies that the `monocdk-experiment`'s package.json references all of the modules under the `@aws-cdk/` namespace. If not, it will add those packages to the list of dependencies. +2. Create build directory - Create a temporary directory will code will be staged for build. +3. Generate `index.ts` - Loop through all directories within the `packages/@aws-cdk` directory of the repository and copy all source code to the buildd directory. Rexport the contents of the copied module from `index.ts` under a namespace based on the modules directory name. +4. Generate module `package.json` - Create the package.json for the build of `monocdk-experiment`. This has no dependencies and includes `constructs` and `@types/node` as devDependencies. +5. Install dependencies - Run `npm install`. +6. Compile with jsii +7. Stage for local consumption - copies the compiled `.js` files from the build directory back to the repository in the `packages/monocdk-experiment/staging` directory. This allows local modules that depend on `monocdk-experiment` to build against it. +8. Package - module is packaged as a normal jsii package using `jsii-pacmak` in the repositories packaging step using `pack.sh`. + +All `@aws-cdk/` namespaced libraries will continue to be published as normal. + +### 2. Pre-release + +`monocdk-experiment` is renamed to `aws-cdk-lib`. The version of this module now becomes v2.0 and is tagged as a "pre-release" version. This has varying formats for different language targets. + +#### NodeJS +version number: `2.0.0-beta.1` +deploying: `npm publish --tag beta` +installing: `npm install aws-cdk-lib@beta` +package.json: +```sh +"dependencies": { + "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`.** + +#### Java +version number: `2.0.0-beta-1` +pom.xml: +```xml + + + software.amazon.awscdk + lib + 2.0.0-beta-1 + + +``` + +#### Dotnet +version number: `2.0.0-beta.1` +.csproj: +```xml + + + +``` + +#### Python +version numbeer: `2.0b1` +requirements.txt: +``` +aws-cdk.lib==2.0b1 +``` + +All `@aws-cdk/` namespaced libraries will continue to be published with current `1.x.x` versions. + +### 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. + +All `@aws-cdk/` namespaced libraries will continue to be published with current `1.x.x` versions. + +### 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. + +## Major Version Rollout Tooling + +To aid in this phased release, some features will need to be added to JSII and other cdk dev tools. These features will help us with rolling out major versions in the future. Whenever a new breaking release occurs, deprecated APIs will be hidden and feature flags will be reset. When we are going through the next cycle of breaking changes, in this case v3.0, then code related to deprecated APIs and feature flags introduced during the preceding major version cycle, v1.0 in this case, can be removed since they no longer will be supported. + +#### [JSII Prerelease Versioning Awareness]() + +In order to support releasing the `aws-cdk-lib` with a prerelease version number, JSII needs to parse the version number of the module its building and recognize it as a "prerelease" and convert it to whatever format is equivalent in the target languages package manager. + +#### [JSII Submodule Support](https://github.com/aws/jsii/issues/1286) + +JSII currently doesn't handle namespacing of exports. Support for this will be needed to allow building the `aws-cdk-lib` module in all of the cdk supported target languages. Though the initial work is complete, some open questions remain about the scope of this feature. Namely, in order to make migrating to the new module structure as easy as possible, [namespace renaming]() could potentially allow C#, Python, and Java users to not have to change the structure of their import statements. + +#### [`aws-cdk-lib` Version Unlocking]() + +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]() + +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: + +An api annotated like so: +```typescript + /** + * @deprecated-v1 + */ + function myDeprecatedApi() {} +``` + +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 + +In addition, linting rules could be created to disallow code deprecated `x` major versions ago". For example, in CDK we could disallow APIs deprecated more than 1 major version cycle old. So in version `3.x.x`, we could throw a lint error and require that this code get removed. + +### [Feature Flag Resetting]() + +Feature flags introduced during the v1 cycle are not allowed to be toggled within v2. This will require users with apps created before a certain feature flag was introduced, to change their code in order to handle the new behavior if they haven't already. + +The CDK should enforce this and ideally also be version aware. If a user has a feature flag configured in their `cdk.context` file that is no longer configurable, due to its introduction being during the previous major version cycle, aws-cdk command line interactions should emit an error instructing the user to remove the feature flag and make any required code changes. Ideally with some information about the specific behavior changes introduced by the feature flag and links to any documentation to help with migration. + +### [Namespace Aware Documentation]() + +Currently, CDK doc generation makes some assumptions about the structure of modules. If we were to generate documentation for the `monocdk-experiment` module with the current doc generation, the left panel of the main documentation site would list only a single module, that being `monocdk-experiment`. Ideally the structure of the documentation will remain similar to how it is today, with all of the immediate children of the top level export showing on the left panel. An exception may have to be made for the contents of the current `@aws-cdk/core` module, since those will all be exposed at the modules top level. Having all of those take up space on the left navigation panel may introduce unwanted noise. + +### Migration Tooling + +In addition to the above changes to build tools, an effort will be made to provide tooling to make migration for users as easy as possible. + +#### [Import Rewriter]() + +A command line tool to change the import statements in an existing cdk application from the old multi-module to the new single module structure. + +for example: +```typescript +import { App, Stack } from '@aws-cdk/core'; +import * as s3 from '@aws-cdk/aws-s3'; +import { Cluster, Service } from '@aws-cdk/aws-ecs'; +``` + +will automatically be changed to: + +```typescript +import { App, Stack } from 'aws-cdk-lib'; +import * as s3 from 'aws-cdk-lib/s3'; +import { Cluster, Service } from 'aws-cdk-lib/ecs'; +``` + +It is not yet known if imports will require change when using other languages. See [namespace renaming]() for more details regarding that. + +#### [Migration Guide]() + +A comprehensive guide for migrating cdk apps from v1 to v2 will be added to the aws-cdk documentation. A place for future migration guides will be defined and a markdown document will be written detailing what steps users should take when upgrading to cdk v2. + +This guide will detail: +1. Installing `aws-cdk-lib` and removing `@aws-cdk/` modules. +2. Upgrading version of `aws-cdk` and other toolchain packages to version `2.x`. +3. Rewriting import statements in source code if necessary, and how to use the [import rewriter]() +4. Removing usage of deprecated APIs. + - List of APIs being deprecated and links to the suggested alternatives for each. +5. Removing references to old feature flags + - List of feature flags being removed and strategy for migrating to new behavior for each. + +### Additional Candidates for Inclusion: + +The following are changes whose implementation's have been identified as requiring a breaking change. Inclusion in the v2 release is up for debate. Arguments to include a specific feature should take into account any increase in cost to the development team required to ship the release, and to users required to migrate their apps to the new version. Though we want to keep both of these costs as low as possible, a breaking release is something that happens relatively infrequently, so the opportunity should be taken to include features determined to have a high payoff to users. + +In addition, since the v1 modules will continue to be supported for some time, and the `aws-cdk-lib` package will be made of up these modules, the inclusion of any of these candidate features would need to be implemented in a way that didn't affect the v1 modules. How this would be done has not been determined, but may be affected by the nature of any particular change. + +#### Recommended + +The following are good candidates for inclusion in this major version release + +- [Easier Identification of Experimental Modules and APIs](https://github.com/aws/aws-cdk-rfcs/issues/116) + +There have been long running discussions about separating experimental APIs into a separate module to make them a more explicit "opt in" feature. Users would either have to install a different module (i.e. `aws-cdk-lib-exerimental`) or import from a different entrypoint (`import * as s3 from 'aws-cdk-lib/experimental`). Since this could be performed at build time and be an optional setting thats turned on or off, it could be introduced in the 2.0 release without affecting the v1 modules, this seems like an ideal time to implement. The technical details of how to achieve this are yet to be determined. + +- [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. + +- [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. + +#### Not Recommended + +The following require more research to be implemented without causing undue breakage. + +- [Unmangled L2 Logical IDs](https://github.com/aws/aws-cdk/issues/1687) + +Changing logical ID generation in any capacity could cost users with existing CDK apps a lot of pain. To deploy their stacks without breaking deployed resources, they may have to change IDs and/or certain property parameters passed to resource constructor functions. Because of this, the change will not be included in the 2.0 release cycle. Future investigation should work towards the potential to implement this behind a feature flag and, if possible, provide users an automated way to make sure resources defined in existing stacks will not have their logical IDs changed causing them to be torn down and replaced unexpectedly. + +- [Removal of All Union Types](https://github.com/aws/aws-cdk/issues/5067) + +JSII's support for union types currently results in the loss of type information in certain language targets when passing data between the JSII and target language runtimes. Removing union types from the cdk codebase to improve user experience in all non-typescript targets would result in breaking some existing public APIs that use them. The current recommendation is to audit the CDK for all union types and APIs that rely on them. These APIs should be marked deprecated and new alternatives should be created. The newly deprecated APIs would be removed as part of the normal major version release process going forward. + +- [Remove Custom Resource Implementation of Fargate Event Target](https://github.com/aws/aws-cdk/issues/3930) + +Investigation should take place to discern if this could be changed without breaking the public API and/or existing stack resources. If not, is creating a new construct and deprecating the old one at the top level a viable strategy for constructs with planned breaking changes going forward? Is it appropriate to deprecate a portion of a construct (constructor properties, etc) that would require resource replacement? Can we guide users through replacement of constructs that are being deprecated to make sure they don't experience interruptions in service? Because of these unknowns, it is unlikely that this will be included in the 2.0 release. + +- [Change Logical IDs to Avoid Potential Collisions](https://github.com/aws/aws-cdk/issues/6421) + +Similar to aws/aws-cdk#1687, changing logical ID logic introduces a lot of problems for existing users. Whether `LogicalIds 2.0` can be implemented behind a feature flag should be investigated to avoid breaking existing apps. + +- [AliasOptions and VersionOptions should not extend EventInvokeConfigOptions](https://github.com/aws/aws-cdk/issues/6966) + +More information needed. @eladb + +- [Remove Support for Docker Assets with Parameters]() + +More information needed. @eladb + +# Drawbacks + +The main drawback of this staged release strategy is the complexity we will incur within our build tooling to be more version aware. Though doing things like selectively including or excluding deprecated APIs based on vurrent version allows us to phase the release of breaking changes without having to maintain a long lived branch for the upcoming release, the potential for bugs in the functionality of these features could have downsides to users. If a deprecated API is removed from a module when it shouldn't be, and that module is published, it will break user's applications. Though this could of course be remedied in a patch release. + +If a deprecated API isn't removed from a version that it was inteded to be, and users start relying on the presence of that API, then by fixing the bug and removing the API in future versions we potentionally introduce breaking changes that weren't intended by us or expected by the users. + +Because of this reason, automated verification of our different builds and the presence/absence of APIs and feature flags is, as always, of high importance. + +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). + +Users may have to make additional code changes when upgrading if they are relying on deprecated APIs or feature flags that are being removed. This cost can be minimized through good documentation and information in the [migration guide](#migration-guide). + +# Rationale and Alternatives + +## 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). + +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". + +Therefore, a major part of the motivation to perform this work is to establish a framework for releasing new major versions of the cdk in a controlled and standardized way. Establishing standards and tools to automatically handle deprecations, feature flag resets, and pre-release versioning will allow the core team and contributors to leverage these to better control breakage. The path to introduce a breaking change is then a lot more clear. + +First we ask, "can this be implemented behind a feature flag"? If so, that's usually the answer. Build tooling tells us when feature flags can be removed and warns users when it has happened. Migration path to new behavior has to be considered and should be documented clearly at the time the flag is created. This goes in the migration guide of the next major version. + +If it can't be implemented behind a feature flag, we ask "can a new code path be defined and the old one deprecated?". Once again, migration path is considered and documented and it goes into the next major version migration guide. + +If the migration path is too painful in either situation, can it be reduced somehow? Can it be automated? etc... + +The desire to move forward with the change in packaging strategy has brought the need for these tools and procedures to the forefront. + +## Alternatives + +The most notable alternative to releasing a new major version, is basically to not. This could be done a couple of ways. + +The first is not moving forward with the packaging change at all. For the argument against that, see the [MonoCDK RFC](https://github.com/aws/aws-cdk-rfcs/issues/6). + +The second is to simply release the new module, `aws-cdk-lib` locked to the same `1.x.x` version that the other modules are currently locked to. In fact, that is the first stage of the release process, its just under the name `monocdk-experiment`. This was a low cost way for the dev team, contributors, and users to experiment with the new structure before investing too much towards it. + +Regardless, the point of using this change to push towards a 2.0 release, is that the single package structure is "the new cdk". Meaning, the long term plan is to only release the `aws-cdk-lib` package and no longer publish the `@aws-cdk/` namespaced ones. The [MonoCDK RFC](https://github.com/aws/aws-cdk-rfcs/issues/6) has more info on the problems currently experienced by users caused by the current packaging strategy and these problems will always exist unless we stop supporting the `@aws-cdk/` packages. + +Since we want to eventually supplant the current module structure with the new one, semver says we have to do it with the release of a major version. + +# Adoption Strategy + +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). + +Users may have to make additional code changes when upgrading if they are relying on deprecated APIs or feature flags that are being removed. A [migration guide](#migration-guide) will be written with details about each individual feature flag and deprecated API that users may need to handle differently when upgrading. + +# Unresolved questions + +The bulk of unresolved questions are listed in the [detailed design](#detailed-design) section. To recap: + +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. + +# Future Possibilities + +As our first major version post 1.0, this sets the tone for others going forward. The 2.0 release is looking to be relatively painless for users to adopt. The only code change required, if any at all, should be completely automated. The challenge for the future is to maintain that experience whenever possible, and wherever it isn't, give users plenty of time and warning to change their code and provide details about a reasonable path to do so without interruptions to their existing cloud resources. From 50310ea12bfcf8d1df4b8ede95543ec9285692eb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BC=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier-Muller?= Date: Mon, 22 Jun 2020 15:46:10 +0200 Subject: [PATCH 02/21] reflow at 120 --- .prettierrc.yaml | 6 + text/0079-cdk-2.0.md | 337 +++++++++++++++++++++++++++++++------------ 2 files changed, 251 insertions(+), 92 deletions(-) create mode 100644 .prettierrc.yaml diff --git a/.prettierrc.yaml b/.prettierrc.yaml new file mode 100644 index 000000000..68eb9c7c5 --- /dev/null +++ b/.prettierrc.yaml @@ -0,0 +1,6 @@ +printWidth: 120 +proseWrap: always +semi: true +singleQuote: true +quoteProps: as-needed +trailingComma: all diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index 3de932ba7..55ced3541 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -6,49 +6,57 @@ related issue: https://github.com/aws/aws-cdk-rfcs/issues/6 --- + # Summary CDK v2.0! -This RFC details the strategy for building and releasing aws-cdk 2.0, in addition to changes to tooling required to support this strategy. For details on the specific features themselves, see the corresponding RFCs. +This RFC details the strategy for building and releasing aws-cdk 2.0, in addition to changes to tooling required to +support this strategy. For details on the specific features themselves, see the corresponding RFCs. # Motivation -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. +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). +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 core motivation of this proposal is to detail the plan required to release this change while continuing to support users referencing the v1 modules. In short, we want to make sure users have plenty of time to transition their code to using the new module structure and make that transition as easy as possible. +The core motivation of this proposal is to detail the plan required to release this change while continuing to support +users referencing the v1 modules. In short, we want to make sure users have plenty of time to transition their code to +using the new module structure and make that transition as easy as possible. # Basic Example ### New Module Structure -*Installing aws-cdk 2.0* +_Installing aws-cdk 2.0_ + ```bash npm install aws-cdk aws-cdk-lib ``` -*Importing modules from aws-cdk 2.0* +_Importing modules from aws-cdk 2.0_ + ```typescript -import { - aws_ecs as ecs, - aws_lambda as lambda, - aws_s3 as s3, -} from 'aws-cdk-lib'; +import { aws_ecs as ecs, aws_lambda as lambda, aws_s3 as s3 } from 'aws-cdk-lib'; ``` -*Importing experimental constructs from aws-cdk 2.0* +_Importing experimental constructs from aws-cdk 2.0_ + ```typescript -import {aws_appsync as appsync_experimental} from 'aws-cdk-lib/experimental' +import { aws_appsync as appsync_experimental } from 'aws-cdk-lib/experimental'; ``` # Design Summary 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. +- [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. - Remove Deprecated APIs - Delete all constructs/methods marked with `@deprecated` flag. - Separate Experimental Code - Extract experimental APIs into a separate entrypoint. @@ -60,40 +68,54 @@ CDK v2.0 will be released in stages. The stages also dictate if and how the v1 m ### 1. Experimental -A module under the name `monocdk-experiment` is created that re-exports the contents of all of the `@aws-cdk/` namespaced modules. The version number of `monocdk-experiment` is locked to the version of all other modules in the monorepo. +A module under the name `monocdk-experiment` is created that re-exports the contents of all of the `@aws-cdk/` +namespaced modules. The version number of `monocdk-experiment` is locked to the version of all other modules in the +monorepo. -`monodk-experiment` has no source code of its own. It is a series of build scripts that creates a module that re-exports all of the code of `@aws-cdk/` packages. The build step peforms these actions: +`monodk-experiment` has no source code of its own. It is a series of build scripts that creates a module that re-exports +all of the code of `@aws-cdk/` packages. The build step peforms these actions: -1. Build and validate package.json - This verifies that the `monocdk-experiment`'s package.json references all of the modules under the `@aws-cdk/` namespace. If not, it will add those packages to the list of dependencies. +1. Build and validate package.json - This verifies that the `monocdk-experiment`'s package.json references all of the + modules under the `@aws-cdk/` namespace. If not, it will add those packages to the list of dependencies. 2. Create build directory - Create a temporary directory will code will be staged for build. -3. Generate `index.ts` - Loop through all directories within the `packages/@aws-cdk` directory of the repository and copy all source code to the buildd directory. Rexport the contents of the copied module from `index.ts` under a namespace based on the modules directory name. -4. Generate module `package.json` - Create the package.json for the build of `monocdk-experiment`. This has no dependencies and includes `constructs` and `@types/node` as devDependencies. +3. Generate `index.ts` - Loop through all directories within the `packages/@aws-cdk` directory of the repository and + copy all source code to the buildd directory. Rexport the contents of the copied module from `index.ts` under a + namespace based on the modules directory name. +4. Generate module `package.json` - Create the package.json for the build of `monocdk-experiment`. This has no + dependencies and includes `constructs` and `@types/node` as devDependencies. 5. Install dependencies - Run `npm install`. 6. Compile with jsii -7. Stage for local consumption - copies the compiled `.js` files from the build directory back to the repository in the `packages/monocdk-experiment/staging` directory. This allows local modules that depend on `monocdk-experiment` to build against it. -8. Package - module is packaged as a normal jsii package using `jsii-pacmak` in the repositories packaging step using `pack.sh`. +7. Stage for local consumption - copies the compiled `.js` files from the build directory back to the repository in the + `packages/monocdk-experiment/staging` directory. This allows local modules that depend on `monocdk-experiment` to + build against it. +8. Package - module is packaged as a normal jsii package using `jsii-pacmak` in the repositories packaging step using + `pack.sh`. All `@aws-cdk/` namespaced libraries will continue to be published as normal. ### 2. Pre-release -`monocdk-experiment` is renamed to `aws-cdk-lib`. The version of this module now becomes v2.0 and is tagged as a "pre-release" version. This has varying formats for different language targets. +`monocdk-experiment` is renamed to `aws-cdk-lib`. The version of this module now becomes v2.0 and is tagged as a +"pre-release" version. This has varying formats for different language targets. #### NodeJS -version number: `2.0.0-beta.1` -deploying: `npm publish --tag beta` -installing: `npm install aws-cdk-lib@beta` + +version number: `2.0.0-beta.1` deploying: `npm publish --tag beta` installing: `npm install aws-cdk-lib@beta` package.json: + ```sh "dependencies": { "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`.** + +> 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`. #### Java -version number: `2.0.0-beta-1` -pom.xml: + +version number: `2.0.0-beta-1` pom.xml: + ```xml @@ -105,8 +127,9 @@ pom.xml: ``` #### Dotnet -version number: `2.0.0-beta.1` -.csproj: + +version number: `2.0.0-beta.1` .csproj: + ```xml @@ -114,8 +137,9 @@ version number: `2.0.0-beta.1` ``` #### Python -version numbeer: `2.0b1` -requirements.txt: + +version numbeer: `2.0b1` requirements.txt: + ``` aws-cdk.lib==2.0b1 ``` @@ -124,7 +148,9 @@ All `@aws-cdk/` namespaced libraries will continue to be published with current ### 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. +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. All `@aws-cdk/` namespaced libraries will continue to be published with current `1.x.x` versions. @@ -132,64 +158,99 @@ All `@aws-cdk/` namespaced libraries will continue to be published with current `@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. +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. ## Major Version Rollout Tooling -To aid in this phased release, some features will need to be added to JSII and other cdk dev tools. These features will help us with rolling out major versions in the future. Whenever a new breaking release occurs, deprecated APIs will be hidden and feature flags will be reset. When we are going through the next cycle of breaking changes, in this case v3.0, then code related to deprecated APIs and feature flags introduced during the preceding major version cycle, v1.0 in this case, can be removed since they no longer will be supported. +To aid in this phased release, some features will need to be added to JSII and other cdk dev tools. These features will +help us with rolling out major versions in the future. Whenever a new breaking release occurs, deprecated APIs will be +hidden and feature flags will be reset. When we are going through the next cycle of breaking changes, in this case v3.0, +then code related to deprecated APIs and feature flags introduced during the preceding major version cycle, v1.0 in this +case, can be removed since they no longer will be supported. #### [JSII Prerelease Versioning Awareness]() -In order to support releasing the `aws-cdk-lib` with a prerelease version number, JSII needs to parse the version number of the module its building and recognize it as a "prerelease" and convert it to whatever format is equivalent in the target languages package manager. +In order to support releasing the `aws-cdk-lib` with a prerelease version number, JSII needs to parse the version number +of the module its building and recognize it as a "prerelease" and convert it to whatever format is equivalent in the +target languages package manager. #### [JSII Submodule Support](https://github.com/aws/jsii/issues/1286) -JSII currently doesn't handle namespacing of exports. Support for this will be needed to allow building the `aws-cdk-lib` module in all of the cdk supported target languages. Though the initial work is complete, some open questions remain about the scope of this feature. Namely, in order to make migrating to the new module structure as easy as possible, [namespace renaming]() could potentially allow C#, Python, and Java users to not have to change the structure of their import statements. +JSII currently doesn't handle namespacing of exports. Support for this will be needed to allow building the +`aws-cdk-lib` module in all of the cdk supported target languages. Though the initial work is complete, some open +questions remain about the scope of this feature. Namely, in order to make migrating to the new module structure as easy +as possible, [namespace renaming]() could potentially allow C#, Python, and Java users to not have to change the +structure of their import statements. #### [`aws-cdk-lib` Version Unlocking]() -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. +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]() -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: +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: An api annotated like so: + ```typescript - /** - * @deprecated-v1 - */ - function myDeprecatedApi() {} +/** + * @deprecated-v1 + */ +function myDeprecatedApi() {} ``` -When inside a module versioned `1.x.x` -`jsii` - builds normally, no warning +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 +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 -In addition, linting rules could be created to disallow code deprecated `x` major versions ago". For example, in CDK we could disallow APIs deprecated more than 1 major version cycle old. So in version `3.x.x`, we could throw a lint error and require that this code get removed. +In addition, linting rules could be created to disallow code deprecated `x` major versions ago". For example, in CDK we +could disallow APIs deprecated more than 1 major version cycle old. So in version `3.x.x`, we could throw a lint error +and require that this code get removed. ### [Feature Flag Resetting]() -Feature flags introduced during the v1 cycle are not allowed to be toggled within v2. This will require users with apps created before a certain feature flag was introduced, to change their code in order to handle the new behavior if they haven't already. +Feature flags introduced during the v1 cycle are not allowed to be toggled within v2. This will require users with apps +created before a certain feature flag was introduced, to change their code in order to handle the new behavior if they +haven't already. -The CDK should enforce this and ideally also be version aware. If a user has a feature flag configured in their `cdk.context` file that is no longer configurable, due to its introduction being during the previous major version cycle, aws-cdk command line interactions should emit an error instructing the user to remove the feature flag and make any required code changes. Ideally with some information about the specific behavior changes introduced by the feature flag and links to any documentation to help with migration. +The CDK should enforce this and ideally also be version aware. If a user has a feature flag configured in their +`cdk.context` file that is no longer configurable, due to its introduction being during the previous major version +cycle, aws-cdk command line interactions should emit an error instructing the user to remove the feature flag and make +any required code changes. Ideally with some information about the specific behavior changes introduced by the feature +flag and links to any documentation to help with migration. ### [Namespace Aware Documentation]() -Currently, CDK doc generation makes some assumptions about the structure of modules. If we were to generate documentation for the `monocdk-experiment` module with the current doc generation, the left panel of the main documentation site would list only a single module, that being `monocdk-experiment`. Ideally the structure of the documentation will remain similar to how it is today, with all of the immediate children of the top level export showing on the left panel. An exception may have to be made for the contents of the current `@aws-cdk/core` module, since those will all be exposed at the modules top level. Having all of those take up space on the left navigation panel may introduce unwanted noise. +Currently, CDK doc generation makes some assumptions about the structure of modules. If we were to generate +documentation for the `monocdk-experiment` module with the current doc generation, the left panel of the main +documentation site would list only a single module, that being `monocdk-experiment`. Ideally the structure of the +documentation will remain similar to how it is today, with all of the immediate children of the top level export showing +on the left panel. An exception may have to be made for the contents of the current `@aws-cdk/core` module, since those +will all be exposed at the modules top level. Having all of those take up space on the left navigation panel may +introduce unwanted noise. ### Migration Tooling -In addition to the above changes to build tools, an effort will be made to provide tooling to make migration for users as easy as possible. +In addition to the above changes to build tools, an effort will be made to provide tooling to make migration for users +as easy as possible. #### [Import Rewriter]() -A command line tool to change the import statements in an existing cdk application from the old multi-module to the new single module structure. +A command line tool to change the import statements in an existing cdk application from the old multi-module to the new +single module structure. for example: + ```typescript import { App, Stack } from '@aws-cdk/core'; import * as s3 from '@aws-cdk/aws-s3'; @@ -204,26 +265,40 @@ import * as s3 from 'aws-cdk-lib/s3'; import { Cluster, Service } from 'aws-cdk-lib/ecs'; ``` -It is not yet known if imports will require change when using other languages. See [namespace renaming]() for more details regarding that. +It is not yet known if imports will require change when using other languages. See [namespace renaming]() for more +details regarding that. #### [Migration Guide]() -A comprehensive guide for migrating cdk apps from v1 to v2 will be added to the aws-cdk documentation. A place for future migration guides will be defined and a markdown document will be written detailing what steps users should take when upgrading to cdk v2. +A comprehensive guide for migrating cdk apps from v1 to v2 will be added to the aws-cdk documentation. A place for +future migration guides will be defined and a markdown document will be written detailing what steps users should take +when upgrading to cdk v2. This guide will detail: + 1. Installing `aws-cdk-lib` and removing `@aws-cdk/` modules. 2. Upgrading version of `aws-cdk` and other toolchain packages to version `2.x`. 3. Rewriting import statements in source code if necessary, and how to use the [import rewriter]() 4. Removing usage of deprecated APIs. - - List of APIs being deprecated and links to the suggested alternatives for each. + +- List of APIs being deprecated and links to the suggested alternatives for each. + 5. Removing references to old feature flags - - List of feature flags being removed and strategy for migrating to new behavior for each. + +- List of feature flags being removed and strategy for migrating to new behavior for each. ### Additional Candidates for Inclusion: -The following are changes whose implementation's have been identified as requiring a breaking change. Inclusion in the v2 release is up for debate. Arguments to include a specific feature should take into account any increase in cost to the development team required to ship the release, and to users required to migrate their apps to the new version. Though we want to keep both of these costs as low as possible, a breaking release is something that happens relatively infrequently, so the opportunity should be taken to include features determined to have a high payoff to users. +The following are changes whose implementation's have been identified as requiring a breaking change. Inclusion in the +v2 release is up for debate. Arguments to include a specific feature should take into account any increase in cost to +the development team required to ship the release, and to users required to migrate their apps to the new version. +Though we want to keep both of these costs as low as possible, a breaking release is something that happens relatively +infrequently, so the opportunity should be taken to include features determined to have a high payoff to users. -In addition, since the v1 modules will continue to be supported for some time, and the `aws-cdk-lib` package will be made of up these modules, the inclusion of any of these candidate features would need to be implemented in a way that didn't affect the v1 modules. How this would be done has not been determined, but may be affected by the nature of any particular change. +In addition, since the v1 modules will continue to be supported for some time, and the `aws-cdk-lib` package will be +made of up these modules, the inclusion of any of these candidate features would need to be implemented in a way that +didn't affect the v1 modules. How this would be done has not been determined, but may be affected by the nature of any +particular change. #### Recommended @@ -231,15 +306,26 @@ The following are good candidates for inclusion in this major version release - [Easier Identification of Experimental Modules and APIs](https://github.com/aws/aws-cdk-rfcs/issues/116) -There have been long running discussions about separating experimental APIs into a separate module to make them a more explicit "opt in" feature. Users would either have to install a different module (i.e. `aws-cdk-lib-exerimental`) or import from a different entrypoint (`import * as s3 from 'aws-cdk-lib/experimental`). Since this could be performed at build time and be an optional setting thats turned on or off, it could be introduced in the 2.0 release without affecting the v1 modules, this seems like an ideal time to implement. The technical details of how to achieve this are yet to be determined. +There have been long running discussions about separating experimental APIs into a separate module to make them a more +explicit "opt in" feature. Users would either have to install a different module (i.e. `aws-cdk-lib-exerimental`) or +import from a different entrypoint (`import * as s3 from 'aws-cdk-lib/experimental`). Since this could be performed at +build time and be an optional setting thats turned on or off, it could be introduced in the 2.0 release without +affecting the v1 modules, this seems like an ideal time to implement. The technical details of how to achieve this are +yet to be determined. - [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. +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. - [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. +`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 @@ -247,19 +333,35 @@ The following require more research to be implemented without causing undue brea - [Unmangled L2 Logical IDs](https://github.com/aws/aws-cdk/issues/1687) -Changing logical ID generation in any capacity could cost users with existing CDK apps a lot of pain. To deploy their stacks without breaking deployed resources, they may have to change IDs and/or certain property parameters passed to resource constructor functions. Because of this, the change will not be included in the 2.0 release cycle. Future investigation should work towards the potential to implement this behind a feature flag and, if possible, provide users an automated way to make sure resources defined in existing stacks will not have their logical IDs changed causing them to be torn down and replaced unexpectedly. +Changing logical ID generation in any capacity could cost users with existing CDK apps a lot of pain. To deploy their +stacks without breaking deployed resources, they may have to change IDs and/or certain property parameters passed to +resource constructor functions. Because of this, the change will not be included in the 2.0 release cycle. Future +investigation should work towards the potential to implement this behind a feature flag and, if possible, provide users +an automated way to make sure resources defined in existing stacks will not have their logical IDs changed causing them +to be torn down and replaced unexpectedly. - [Removal of All Union Types](https://github.com/aws/aws-cdk/issues/5067) -JSII's support for union types currently results in the loss of type information in certain language targets when passing data between the JSII and target language runtimes. Removing union types from the cdk codebase to improve user experience in all non-typescript targets would result in breaking some existing public APIs that use them. The current recommendation is to audit the CDK for all union types and APIs that rely on them. These APIs should be marked deprecated and new alternatives should be created. The newly deprecated APIs would be removed as part of the normal major version release process going forward. +JSII's support for union types currently results in the loss of type information in certain language targets when +passing data between the JSII and target language runtimes. Removing union types from the cdk codebase to improve user +experience in all non-typescript targets would result in breaking some existing public APIs that use them. The current +recommendation is to audit the CDK for all union types and APIs that rely on them. These APIs should be marked +deprecated and new alternatives should be created. The newly deprecated APIs would be removed as part of the normal +major version release process going forward. - [Remove Custom Resource Implementation of Fargate Event Target](https://github.com/aws/aws-cdk/issues/3930) -Investigation should take place to discern if this could be changed without breaking the public API and/or existing stack resources. If not, is creating a new construct and deprecating the old one at the top level a viable strategy for constructs with planned breaking changes going forward? Is it appropriate to deprecate a portion of a construct (constructor properties, etc) that would require resource replacement? Can we guide users through replacement of constructs that are being deprecated to make sure they don't experience interruptions in service? Because of these unknowns, it is unlikely that this will be included in the 2.0 release. +Investigation should take place to discern if this could be changed without breaking the public API and/or existing +stack resources. If not, is creating a new construct and deprecating the old one at the top level a viable strategy for +constructs with planned breaking changes going forward? Is it appropriate to deprecate a portion of a construct +(constructor properties, etc) that would require resource replacement? Can we guide users through replacement of +constructs that are being deprecated to make sure they don't experience interruptions in service? Because of these +unknowns, it is unlikely that this will be included in the 2.0 release. - [Change Logical IDs to Avoid Potential Collisions](https://github.com/aws/aws-cdk/issues/6421) -Similar to aws/aws-cdk#1687, changing logical ID logic introduces a lot of problems for existing users. Whether `LogicalIds 2.0` can be implemented behind a feature flag should be investigated to avoid breaking existing apps. +Similar to aws/aws-cdk#1687, changing logical ID logic introduces a lot of problems for existing users. Whether +`LogicalIds 2.0` can be implemented behind a feature flag should be investigated to avoid breaking existing apps. - [AliasOptions and VersionOptions should not extend EventInvokeConfigOptions](https://github.com/aws/aws-cdk/issues/6966) @@ -271,67 +373,118 @@ More information needed. @eladb # Drawbacks -The main drawback of this staged release strategy is the complexity we will incur within our build tooling to be more version aware. Though doing things like selectively including or excluding deprecated APIs based on vurrent version allows us to phase the release of breaking changes without having to maintain a long lived branch for the upcoming release, the potential for bugs in the functionality of these features could have downsides to users. If a deprecated API is removed from a module when it shouldn't be, and that module is published, it will break user's applications. Though this could of course be remedied in a patch release. +The main drawback of this staged release strategy is the complexity we will incur within our build tooling to be more +version aware. Though doing things like selectively including or excluding deprecated APIs based on vurrent version +allows us to phase the release of breaking changes without having to maintain a long lived branch for the upcoming +release, the potential for bugs in the functionality of these features could have downsides to users. If a deprecated +API is removed from a module when it shouldn't be, and that module is published, it will break user's applications. +Though this could of course be remedied in a patch release. -If a deprecated API isn't removed from a version that it was inteded to be, and users start relying on the presence of that API, then by fixing the bug and removing the API in future versions we potentionally introduce breaking changes that weren't intended by us or expected by the users. +If a deprecated API isn't removed from a version that it was inteded to be, and users start relying on the presence of +that API, then by fixing the bug and removing the API in future versions we potentionally introduce breaking changes +that weren't intended by us or expected by the users. -Because of this reason, automated verification of our different builds and the presence/absence of APIs and feature flags is, as always, of high importance. +Because of this reason, automated verification of our different builds and the presence/absence of APIs and feature +flags is, as always, of high importance. -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: +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). +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). -Users may have to make additional code changes when upgrading if they are relying on deprecated APIs or feature flags that are being removed. This cost can be minimized through good documentation and information in the [migration guide](#migration-guide). +Users may have to make additional code changes when upgrading if they are relying on deprecated APIs or feature flags +that are being removed. This cost can be minimized through good documentation and information in the +[migration guide](#migration-guide). # Rationale and Alternatives ## 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). +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". +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". -Therefore, a major part of the motivation to perform this work is to establish a framework for releasing new major versions of the cdk in a controlled and standardized way. Establishing standards and tools to automatically handle deprecations, feature flag resets, and pre-release versioning will allow the core team and contributors to leverage these to better control breakage. The path to introduce a breaking change is then a lot more clear. +Therefore, a major part of the motivation to perform this work is to establish a framework for releasing new major +versions of the cdk in a controlled and standardized way. Establishing standards and tools to automatically handle +deprecations, feature flag resets, and pre-release versioning will allow the core team and contributors to leverage +these to better control breakage. The path to introduce a breaking change is then a lot more clear. -First we ask, "can this be implemented behind a feature flag"? If so, that's usually the answer. Build tooling tells us when feature flags can be removed and warns users when it has happened. Migration path to new behavior has to be considered and should be documented clearly at the time the flag is created. This goes in the migration guide of the next major version. +First we ask, "can this be implemented behind a feature flag"? If so, that's usually the answer. Build tooling tells us +when feature flags can be removed and warns users when it has happened. Migration path to new behavior has to be +considered and should be documented clearly at the time the flag is created. This goes in the migration guide of the +next major version. -If it can't be implemented behind a feature flag, we ask "can a new code path be defined and the old one deprecated?". Once again, migration path is considered and documented and it goes into the next major version migration guide. +If it can't be implemented behind a feature flag, we ask "can a new code path be defined and the old one deprecated?". +Once again, migration path is considered and documented and it goes into the next major version migration guide. If the migration path is too painful in either situation, can it be reduced somehow? Can it be automated? etc... -The desire to move forward with the change in packaging strategy has brought the need for these tools and procedures to the forefront. +The desire to move forward with the change in packaging strategy has brought the need for these tools and procedures to +the forefront. ## Alternatives The most notable alternative to releasing a new major version, is basically to not. This could be done a couple of ways. -The first is not moving forward with the packaging change at all. For the argument against that, see the [MonoCDK RFC](https://github.com/aws/aws-cdk-rfcs/issues/6). +The first is not moving forward with the packaging change at all. For the argument against that, see the +[MonoCDK RFC](https://github.com/aws/aws-cdk-rfcs/issues/6). -The second is to simply release the new module, `aws-cdk-lib` locked to the same `1.x.x` version that the other modules are currently locked to. In fact, that is the first stage of the release process, its just under the name `monocdk-experiment`. This was a low cost way for the dev team, contributors, and users to experiment with the new structure before investing too much towards it. +The second is to simply release the new module, `aws-cdk-lib` locked to the same `1.x.x` version that the other modules +are currently locked to. In fact, that is the first stage of the release process, its just under the name +`monocdk-experiment`. This was a low cost way for the dev team, contributors, and users to experiment with the new +structure before investing too much towards it. -Regardless, the point of using this change to push towards a 2.0 release, is that the single package structure is "the new cdk". Meaning, the long term plan is to only release the `aws-cdk-lib` package and no longer publish the `@aws-cdk/` namespaced ones. The [MonoCDK RFC](https://github.com/aws/aws-cdk-rfcs/issues/6) has more info on the problems currently experienced by users caused by the current packaging strategy and these problems will always exist unless we stop supporting the `@aws-cdk/` packages. +Regardless, the point of using this change to push towards a 2.0 release, is that the single package structure is "the +new cdk". Meaning, the long term plan is to only release the `aws-cdk-lib` package and no longer publish the `@aws-cdk/` +namespaced ones. The [MonoCDK RFC](https://github.com/aws/aws-cdk-rfcs/issues/6) has more info on the problems currently +experienced by users caused by the current packaging strategy and these problems will always exist unless we stop +supporting the `@aws-cdk/` packages. -Since we want to eventually supplant the current module structure with the new one, semver says we have to do it with the release of a major version. +Since we want to eventually supplant the current module structure with the new one, semver says we have to do it with +the release of a major version. # Adoption Strategy 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). +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). -Users may have to make additional code changes when upgrading if they are relying on deprecated APIs or feature flags that are being removed. A [migration guide](#migration-guide) will be written with details about each individual feature flag and deprecated API that users may need to handle differently when upgrading. +Users may have to make additional code changes when upgrading if they are relying on deprecated APIs or feature flags +that are being removed. A [migration guide](#migration-guide) will be written with details about each individual feature +flag and deprecated API that users may need to handle differently when upgrading. # Unresolved questions The bulk of unresolved questions are listed in the [detailed design](#detailed-design) section. To recap: -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? +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. +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. # Future Possibilities -As our first major version post 1.0, this sets the tone for others going forward. The 2.0 release is looking to be relatively painless for users to adopt. The only code change required, if any at all, should be completely automated. The challenge for the future is to maintain that experience whenever possible, and wherever it isn't, give users plenty of time and warning to change their code and provide details about a reasonable path to do so without interruptions to their existing cloud resources. +As our first major version post 1.0, this sets the tone for others going forward. The 2.0 release is looking to be +relatively painless for users to adopt. The only code change required, if any at all, should be completely automated. +The challenge for the future is to maintain that experience whenever possible, and wherever it isn't, give users plenty +of time and warning to change their code and provide details about a reasonable path to do so without interruptions to +their existing cloud resources. From aa900c30634d92e0313e5c0e2358761a6b32c4c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BC=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier-Muller?= Date: Mon, 29 Jun 2020 15:35:38 +0200 Subject: [PATCH 03/21] updates on new v2 scope and foking strategy --- README.md | 355 +++++++++++++++++++------------------------ text/0079-cdk-2.0.md | 350 ++++++++++++++++-------------------------- 2 files changed, 285 insertions(+), 420 deletions(-) diff --git a/README.md b/README.md index f5a93871d..03e33861a 100644 --- a/README.md +++ b/README.md @@ -1,100 +1,95 @@ # AWS CDK RFCs -This repo is a place to propose and track upcoming changes to [AWS CDK], [jsii], and -other related projects. It also is a great place to learn about the current and -future state of the libraries and to discover projects for contribution. +This repo is a place to propose and track upcoming changes to [AWS CDK], [jsii], and other related projects. It also is +a great place to learn about the current and future state of the libraries and to discover projects for contribution. -[AWS CDK]: https://github.com/aws/aws-cdk +[aws cdk]: https://github.com/aws/aws-cdk [jsii]: https://github.com/aws/jsii -See [The RFC Life Cycle](#the-rfc-life-cycle) to learn more about the states of -existing proposals. +See [The RFC Life Cycle](#the-rfc-life-cycle) to learn more about the states of existing proposals. -\#|Title|Owner|Status ----|-----|-----|------ -[110](https://github.com/aws/aws-cdk-rfcs/issues/110)|[CLI Compatibility Strategy](https://github.com/aws/aws-cdk-rfcs/blob/master/text/00110-cli-framework-compatibility-strategy.md)|[@iliapolo](https://github.com/iliapolo)|ready -[95](https://github.com/aws/aws-cdk-rfcs/issues/95)|[Cognito Construct Library](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0095-cognito-construct-library)|[@nija-at](https://github.com/nija-at)|ready -[92](https://github.com/aws/aws-cdk-rfcs/issues/92)|[CI/CD Asset Publishing](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0092-asset-publishing.md)|[@rix0rrr](https://github.com/rix0rrr)|ready -[49](https://github.com/aws/aws-cdk-rfcs/issues/49)|[CI/CD for CDK apps](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0049-continuous-delivery.md)|[@rix0rrr](https://github.com/rix0rrr)|ready -[6](https://github.com/aws/aws-cdk-rfcs/issues/6)|[Monolithic Packaging](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0006-monolothic-packaging.md)|[@eladb](https://github.com/eladb)|ready -[79](https://github.com/aws/aws-cdk-rfcs/issues/79)|[CDK v2.0](https://github.com/aws/aws-cdk-rfcs/issues/79)|[@MrArnoldPalmer](https://github.com/MrArnoldPalmer)|pending -[60](https://github.com/aws/aws-cdk-rfcs/issues/60)|[Bazel Build System](https://github.com/aws/aws-cdk-rfcs/pull/61)||pending -[139](https://github.com/aws/aws-cdk-rfcs/issues/139)|["fromLookup" for additional resources](https://github.com/aws/aws-cdk-rfcs/issues/139)||proposed -[127](https://github.com/aws/aws-cdk-rfcs/issues/127)|[CDK to directly reference/import/update an existing stack](https://github.com/aws/aws-cdk-rfcs/issues/127)||proposed -[118](https://github.com/aws/aws-cdk-rfcs/issues/118)|[New CDK Major Version](https://github.com/aws/aws-cdk-rfcs/issues/118)||proposed -[116](https://github.com/aws/aws-cdk-rfcs/issues/116)|[Easier identification of experimental modules](https://github.com/aws/aws-cdk-rfcs/issues/116)|[@rix0rrr](https://github.com/rix0rrr)|proposed -[109](https://github.com/aws/aws-cdk-rfcs/issues/109)|[Elasticache L2 Constructs](https://github.com/aws/aws-cdk-rfcs/issues/109)||proposed -[107](https://github.com/aws/aws-cdk-rfcs/issues/107)|[Publish a Construct Library Module Lifecycle document](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0107-construct-library-module-lifecycle.md)|[@ccfife](https://github.com/ccfife)|proposed -[87](https://github.com/aws/aws-cdk-rfcs/issues/87)|[On-Demand CFN Resource Generator](https://github.com/aws/aws-cdk-rfcs/issues/87)||proposed -[72](https://github.com/aws/aws-cdk-rfcs/issues/72)|[Stack Policy](https://github.com/aws/aws-cdk-rfcs/issues/72)||proposed -[64](https://github.com/aws/aws-cdk-rfcs/issues/64)|[Garbage Collection for Assets](https://github.com/aws/aws-cdk-rfcs/issues/64)||proposed -[63](https://github.com/aws/aws-cdk-rfcs/issues/63)|[CDK in Secure Environments](https://github.com/aws/aws-cdk-rfcs/issues/63)||proposed -[58](https://github.com/aws/aws-cdk-rfcs/issues/58)|[Improved ergonomics for stack default environment](https://github.com/aws/aws-cdk-rfcs/issues/58)||proposed -[52](https://github.com/aws/aws-cdk-rfcs/issues/52)|[Support resource import](https://github.com/aws/aws-cdk-rfcs/issues/52)||proposed -[51](https://github.com/aws/aws-cdk-rfcs/issues/51)|[Standardize security groups](https://github.com/aws/aws-cdk-rfcs/issues/51)||proposed -[48](https://github.com/aws/aws-cdk-rfcs/issues/48)|[Faster builds](https://github.com/aws/aws-cdk-rfcs/issues/48)|[@rix0rrr](https://github.com/rix0rrr)|proposed -[46](https://github.com/aws/aws-cdk-rfcs/issues/46)|[Hooks](https://github.com/aws/aws-cdk-rfcs/issues/46)||proposed -[40](https://github.com/aws/aws-cdk-rfcs/issues/40)|[Stack traces across language boundaries](https://github.com/aws/aws-cdk-rfcs/issues/40)||proposed -[39](https://github.com/aws/aws-cdk-rfcs/issues/39)|[Release public artifacts (lambda layers for custom resources, docker images)](https://github.com/aws/aws-cdk-rfcs/issues/39)||proposed -[35](https://github.com/aws/aws-cdk-rfcs/issues/35)|[Publish construct library guidelines](https://github.com/aws/aws-cdk-rfcs/issues/35)||proposed -[34](https://github.com/aws/aws-cdk-rfcs/issues/34)|[Third-party construct ecosystem](https://github.com/aws/aws-cdk-rfcs/issues/34)||proposed -[32](https://github.com/aws/aws-cdk-rfcs/issues/32)|[App-centric operational experience](https://github.com/aws/aws-cdk-rfcs/issues/32)||proposed -[31](https://github.com/aws/aws-cdk-rfcs/issues/31)|[Integration tests](https://github.com/aws/aws-cdk-rfcs/issues/31)||proposed -[30](https://github.com/aws/aws-cdk-rfcs/issues/30)|[Improve synthesized template output](https://github.com/aws/aws-cdk-rfcs/issues/30)||proposed -[28](https://github.com/aws/aws-cdk-rfcs/issues/28)|[Construct library graduation process](https://github.com/aws/aws-cdk-rfcs/issues/28)||proposed -[27](https://github.com/aws/aws-cdk-rfcs/issues/27)|[200 resource limit tools & guidance](https://github.com/aws/aws-cdk-rfcs/issues/27)||proposed -[26](https://github.com/aws/aws-cdk-rfcs/issues/26)|[Monitoring packs](https://github.com/aws/aws-cdk-rfcs/issues/26)||proposed -[25](https://github.com/aws/aws-cdk-rfcs/issues/25)|[Defaults & configuration policy](https://github.com/aws/aws-cdk-rfcs/issues/25)||proposed -[24](https://github.com/aws/aws-cdk-rfcs/issues/24)|[Resource imports](https://github.com/aws/aws-cdk-rfcs/issues/24)||proposed -[23](https://github.com/aws/aws-cdk-rfcs/issues/23)|[Stateful resource support](https://github.com/aws/aws-cdk-rfcs/issues/23)||proposed -[22](https://github.com/aws/aws-cdk-rfcs/issues/22)|[Cost calculator](https://github.com/aws/aws-cdk-rfcs/issues/22)||proposed -[21](https://github.com/aws/aws-cdk-rfcs/issues/21)|[CDK Explorer Roadmap](https://github.com/aws/aws-cdk-rfcs/issues/21)||proposed -[20](https://github.com/aws/aws-cdk-rfcs/issues/20)|[Security posture summary](https://github.com/aws/aws-cdk-rfcs/issues/20)||proposed -[19](https://github.com/aws/aws-cdk-rfcs/issues/19)|[Introspection API](https://github.com/aws/aws-cdk-rfcs/issues/19)||proposed -[18](https://github.com/aws/aws-cdk-rfcs/issues/18)|[Open context provider framework](https://github.com/aws/aws-cdk-rfcs/issues/18)||proposed -[17](https://github.com/aws/aws-cdk-rfcs/issues/17)|[CLI support for multiple-environments](https://github.com/aws/aws-cdk-rfcs/issues/17)||proposed -[15](https://github.com/aws/aws-cdk-rfcs/issues/15)|[Scaffolding](https://github.com/aws/aws-cdk-rfcs/issues/15)||proposed -[14](https://github.com/aws/aws-cdk-rfcs/issues/14)|[Toolchain 2.0](https://github.com/aws/aws-cdk-rfcs/issues/14)|[@shivlaks](https://github.com/shivlaks)|proposed -[13](https://github.com/aws/aws-cdk-rfcs/issues/13)|[Improvements to Reference docs](https://github.com/aws/aws-cdk-rfcs/issues/13)||proposed -[10](https://github.com/aws/aws-cdk-rfcs/issues/10)|[New workshop modules](https://github.com/aws/aws-cdk-rfcs/issues/10)||proposed -[9](https://github.com/aws/aws-cdk-rfcs/issues/9)|[Master developer guide sources in main repo](https://github.com/aws/aws-cdk-rfcs/issues/9)||proposed -[8](https://github.com/aws/aws-cdk-rfcs/issues/8)|[Project structure guidelines](https://github.com/aws/aws-cdk-rfcs/issues/8)||proposed -[7](https://github.com/aws/aws-cdk-rfcs/issues/7)|[Lambda Bundles](https://github.com/aws/aws-cdk-rfcs/issues/7)||proposed -[5](https://github.com/aws/aws-cdk-rfcs/issues/5)|[Security-restricted environments](https://github.com/aws/aws-cdk-rfcs/issues/5)||proposed -[4](https://github.com/aws/aws-cdk-rfcs/issues/4)|[CDK Testing Tools](https://github.com/aws/aws-cdk-rfcs/issues/4)|[@nija-at](https://github.com/nija-at)|proposed -[3](https://github.com/aws/aws-cdk-rfcs/issues/3)|[Integrate CLI into Native Modules](https://github.com/aws/aws-cdk-rfcs/issues/3)||proposed -[2](https://github.com/aws/aws-cdk-rfcs/issues/2)|[Migration Paths](https://github.com/aws/aws-cdk-rfcs/issues/2)||proposed -[1](https://github.com/aws/aws-cdk-rfcs/issues/1)|[CDK Watch](https://github.com/aws/aws-cdk-rfcs/issues/1)||proposed -[55](https://github.com/aws/aws-cdk-rfcs/issues/55)|[Feature Flags](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0055-feature-flags.md)|[@eladb](https://github.com/eladb)|resolved -[37](https://github.com/aws/aws-cdk-rfcs/issues/37)|[Release from a "release" branch](https://github.com/aws/aws-cdk-rfcs/issues/37)|[@MrArnoldPalmer](https://github.com/MrArnoldPalmer)|resolved -[36](https://github.com/aws/aws-cdk-rfcs/issues/36)|[Constructs Programming Model](https://github.com/aws/aws-cdk-rfcs/issues/36)|[@eladb](https://github.com/eladb)|resolved -[16](https://github.com/aws/aws-cdk-rfcs/issues/16)|[RFC Process](https://github.com/aws/aws-cdk-rfcs/pull/53)|[@MrArnoldPalmer](https://github.com/MrArnoldPalmer)|resolved + +| \# | Title | Owner | Status | +| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | -------- | +| [110](https://github.com/aws/aws-cdk-rfcs/issues/110) | [CLI Compatibility Strategy](https://github.com/aws/aws-cdk-rfcs/blob/master/text/00110-cli-framework-compatibility-strategy.md) | [@iliapolo](https://github.com/iliapolo) | ready | +| [95](https://github.com/aws/aws-cdk-rfcs/issues/95) | [Cognito Construct Library](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0095-cognito-construct-library) | [@nija-at](https://github.com/nija-at) | ready | +| [92](https://github.com/aws/aws-cdk-rfcs/issues/92) | [CI/CD Asset Publishing](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0092-asset-publishing.md) | [@rix0rrr](https://github.com/rix0rrr) | ready | +| [49](https://github.com/aws/aws-cdk-rfcs/issues/49) | [CI/CD for CDK apps](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0049-continuous-delivery.md) | [@rix0rrr](https://github.com/rix0rrr) | ready | +| [6](https://github.com/aws/aws-cdk-rfcs/issues/6) | [Monolithic Packaging](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0006-monolothic-packaging.md) | [@eladb](https://github.com/eladb) | ready | +| [79](https://github.com/aws/aws-cdk-rfcs/issues/79) | [CDK v2.0](https://github.com/aws/aws-cdk-rfcs/issues/79) | [@RomainMuller](https://github.com/RomainMuller) | pending | +| [60](https://github.com/aws/aws-cdk-rfcs/issues/60) | [Bazel Build System](https://github.com/aws/aws-cdk-rfcs/pull/61) | | pending | +| [139](https://github.com/aws/aws-cdk-rfcs/issues/139) | ["fromLookup" for additional resources](https://github.com/aws/aws-cdk-rfcs/issues/139) | | proposed | +| [127](https://github.com/aws/aws-cdk-rfcs/issues/127) | [CDK to directly reference/import/update an existing stack](https://github.com/aws/aws-cdk-rfcs/issues/127) | | proposed | +| [118](https://github.com/aws/aws-cdk-rfcs/issues/118) | [New CDK Major Version](https://github.com/aws/aws-cdk-rfcs/issues/118) | | proposed | +| [116](https://github.com/aws/aws-cdk-rfcs/issues/116) | [Easier identification of experimental modules](https://github.com/aws/aws-cdk-rfcs/issues/116) | [@rix0rrr](https://github.com/rix0rrr) | proposed | +| [109](https://github.com/aws/aws-cdk-rfcs/issues/109) | [Elasticache L2 Constructs](https://github.com/aws/aws-cdk-rfcs/issues/109) | | proposed | +| [107](https://github.com/aws/aws-cdk-rfcs/issues/107) | [Publish a Construct Library Module Lifecycle document](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0107-construct-library-module-lifecycle.md) | [@ccfife](https://github.com/ccfife) | proposed | +| [87](https://github.com/aws/aws-cdk-rfcs/issues/87) | [On-Demand CFN Resource Generator](https://github.com/aws/aws-cdk-rfcs/issues/87) | | proposed | +| [72](https://github.com/aws/aws-cdk-rfcs/issues/72) | [Stack Policy](https://github.com/aws/aws-cdk-rfcs/issues/72) | | proposed | +| [64](https://github.com/aws/aws-cdk-rfcs/issues/64) | [Garbage Collection for Assets](https://github.com/aws/aws-cdk-rfcs/issues/64) | | proposed | +| [63](https://github.com/aws/aws-cdk-rfcs/issues/63) | [CDK in Secure Environments](https://github.com/aws/aws-cdk-rfcs/issues/63) | | proposed | +| [58](https://github.com/aws/aws-cdk-rfcs/issues/58) | [Improved ergonomics for stack default environment](https://github.com/aws/aws-cdk-rfcs/issues/58) | | proposed | +| [52](https://github.com/aws/aws-cdk-rfcs/issues/52) | [Support resource import](https://github.com/aws/aws-cdk-rfcs/issues/52) | | proposed | +| [51](https://github.com/aws/aws-cdk-rfcs/issues/51) | [Standardize security groups](https://github.com/aws/aws-cdk-rfcs/issues/51) | | proposed | +| [48](https://github.com/aws/aws-cdk-rfcs/issues/48) | [Faster builds](https://github.com/aws/aws-cdk-rfcs/issues/48) | [@rix0rrr](https://github.com/rix0rrr) | proposed | +| [46](https://github.com/aws/aws-cdk-rfcs/issues/46) | [Hooks](https://github.com/aws/aws-cdk-rfcs/issues/46) | | proposed | +| [40](https://github.com/aws/aws-cdk-rfcs/issues/40) | [Stack traces across language boundaries](https://github.com/aws/aws-cdk-rfcs/issues/40) | | proposed | +| [39](https://github.com/aws/aws-cdk-rfcs/issues/39) | [Release public artifacts (lambda layers for custom resources, docker images)](https://github.com/aws/aws-cdk-rfcs/issues/39) | | proposed | +| [35](https://github.com/aws/aws-cdk-rfcs/issues/35) | [Publish construct library guidelines](https://github.com/aws/aws-cdk-rfcs/issues/35) | | proposed | +| [34](https://github.com/aws/aws-cdk-rfcs/issues/34) | [Third-party construct ecosystem](https://github.com/aws/aws-cdk-rfcs/issues/34) | | proposed | +| [32](https://github.com/aws/aws-cdk-rfcs/issues/32) | [App-centric operational experience](https://github.com/aws/aws-cdk-rfcs/issues/32) | | proposed | +| [31](https://github.com/aws/aws-cdk-rfcs/issues/31) | [Integration tests](https://github.com/aws/aws-cdk-rfcs/issues/31) | | proposed | +| [30](https://github.com/aws/aws-cdk-rfcs/issues/30) | [Improve synthesized template output](https://github.com/aws/aws-cdk-rfcs/issues/30) | | proposed | +| [28](https://github.com/aws/aws-cdk-rfcs/issues/28) | [Construct library graduation process](https://github.com/aws/aws-cdk-rfcs/issues/28) | | proposed | +| [27](https://github.com/aws/aws-cdk-rfcs/issues/27) | [200 resource limit tools & guidance](https://github.com/aws/aws-cdk-rfcs/issues/27) | | proposed | +| [26](https://github.com/aws/aws-cdk-rfcs/issues/26) | [Monitoring packs](https://github.com/aws/aws-cdk-rfcs/issues/26) | | proposed | +| [25](https://github.com/aws/aws-cdk-rfcs/issues/25) | [Defaults & configuration policy](https://github.com/aws/aws-cdk-rfcs/issues/25) | | proposed | +| [24](https://github.com/aws/aws-cdk-rfcs/issues/24) | [Resource imports](https://github.com/aws/aws-cdk-rfcs/issues/24) | | proposed | +| [23](https://github.com/aws/aws-cdk-rfcs/issues/23) | [Stateful resource support](https://github.com/aws/aws-cdk-rfcs/issues/23) | | proposed | +| [22](https://github.com/aws/aws-cdk-rfcs/issues/22) | [Cost calculator](https://github.com/aws/aws-cdk-rfcs/issues/22) | | proposed | +| [21](https://github.com/aws/aws-cdk-rfcs/issues/21) | [CDK Explorer Roadmap](https://github.com/aws/aws-cdk-rfcs/issues/21) | | proposed | +| [20](https://github.com/aws/aws-cdk-rfcs/issues/20) | [Security posture summary](https://github.com/aws/aws-cdk-rfcs/issues/20) | | proposed | +| [19](https://github.com/aws/aws-cdk-rfcs/issues/19) | [Introspection API](https://github.com/aws/aws-cdk-rfcs/issues/19) | | proposed | +| [18](https://github.com/aws/aws-cdk-rfcs/issues/18) | [Open context provider framework](https://github.com/aws/aws-cdk-rfcs/issues/18) | | proposed | +| [17](https://github.com/aws/aws-cdk-rfcs/issues/17) | [CLI support for multiple-environments](https://github.com/aws/aws-cdk-rfcs/issues/17) | | proposed | +| [15](https://github.com/aws/aws-cdk-rfcs/issues/15) | [Scaffolding](https://github.com/aws/aws-cdk-rfcs/issues/15) | | proposed | +| [14](https://github.com/aws/aws-cdk-rfcs/issues/14) | [Toolchain 2.0](https://github.com/aws/aws-cdk-rfcs/issues/14) | [@shivlaks](https://github.com/shivlaks) | proposed | +| [13](https://github.com/aws/aws-cdk-rfcs/issues/13) | [Improvements to Reference docs](https://github.com/aws/aws-cdk-rfcs/issues/13) | | proposed | +| [10](https://github.com/aws/aws-cdk-rfcs/issues/10) | [New workshop modules](https://github.com/aws/aws-cdk-rfcs/issues/10) | | proposed | +| [9](https://github.com/aws/aws-cdk-rfcs/issues/9) | [Master developer guide sources in main repo](https://github.com/aws/aws-cdk-rfcs/issues/9) | | proposed | +| [8](https://github.com/aws/aws-cdk-rfcs/issues/8) | [Project structure guidelines](https://github.com/aws/aws-cdk-rfcs/issues/8) | | proposed | +| [7](https://github.com/aws/aws-cdk-rfcs/issues/7) | [Lambda Bundles](https://github.com/aws/aws-cdk-rfcs/issues/7) | | proposed | +| [5](https://github.com/aws/aws-cdk-rfcs/issues/5) | [Security-restricted environments](https://github.com/aws/aws-cdk-rfcs/issues/5) | | proposed | +| [4](https://github.com/aws/aws-cdk-rfcs/issues/4) | [CDK Testing Tools](https://github.com/aws/aws-cdk-rfcs/issues/4) | [@nija-at](https://github.com/nija-at) | proposed | +| [3](https://github.com/aws/aws-cdk-rfcs/issues/3) | [Integrate CLI into Native Modules](https://github.com/aws/aws-cdk-rfcs/issues/3) | | proposed | +| [2](https://github.com/aws/aws-cdk-rfcs/issues/2) | [Migration Paths](https://github.com/aws/aws-cdk-rfcs/issues/2) | | proposed | +| [1](https://github.com/aws/aws-cdk-rfcs/issues/1) | [CDK Watch](https://github.com/aws/aws-cdk-rfcs/issues/1) | | proposed | +| [55](https://github.com/aws/aws-cdk-rfcs/issues/55) | [Feature Flags](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0055-feature-flags.md) | [@eladb](https://github.com/eladb) | resolved | +| [37](https://github.com/aws/aws-cdk-rfcs/issues/37) | [Release from a "release" branch](https://github.com/aws/aws-cdk-rfcs/issues/37) | [@MrArnoldPalmer](https://github.com/MrArnoldPalmer) | resolved | +| [36](https://github.com/aws/aws-cdk-rfcs/issues/36) | [Constructs Programming Model](https://github.com/aws/aws-cdk-rfcs/issues/36) | [@eladb](https://github.com/eladb) | resolved | +| [16](https://github.com/aws/aws-cdk-rfcs/issues/16) | [RFC Process](https://github.com/aws/aws-cdk-rfcs/pull/53) | [@MrArnoldPalmer](https://github.com/MrArnoldPalmer) | resolved | + ## What does all this mean? -This document is a lot of information about process thats meant to help guide. -It is not a set of rules that need to be strictly applied. It is designed to -help contributors (and thats you!) become more involved with the tools that they +This document is a lot of information about process thats meant to help guide. It is not a set of rules that need to be +strictly applied. It is designed to help contributors (and thats you!) become more involved with the tools that they rely on. All efforts to contribute are encouraged and appreciated. ## What is an RFC? -An RFC is a document that proposes and details a change or addition to the CDK, -JSII, and other related tooling. It also is a process for reviewing and -discussing the proposal and tracking its implementation. "Request for Comments" -means a request for discussion and oversight about the future of the CDK and -JSII from contributors and users. It is an open forum for suggestions, -questions, and feedback. +An RFC is a document that proposes and details a change or addition to the CDK, JSII, and other related tooling. It also +is a process for reviewing and discussing the proposal and tracking its implementation. "Request for Comments" means a +request for discussion and oversight about the future of the CDK and JSII from contributors and users. It is an open +forum for suggestions, questions, and feedback. -The process is intended to be as lightweight and reasonable as possible for the -present circumstances. As usual, we are trying to let the process be driven by -consensus and community norms, not impose more structure than necessary. +The process is intended to be as lightweight and reasonable as possible for the present circumstances. As usual, we are +trying to let the process be driven by consensus and community norms, not impose more structure than necessary. -The RFC process itself is subject to changes as dictated by the core team and -the community. Proposals can include proposed changes to the RFC process itself -to better serve contributors. +The RFC process itself is subject to changes as dictated by the core team and the community. Proposals can include +proposed changes to the RFC process itself to better serve contributors. ## Contributions @@ -102,117 +97,95 @@ Contributions are welcome from anyone in a variety of ways. - [Reviewing and dicussing existing proposals](#reviewing-rfcs) -Comments are welcome on proposal tracking issues and RFC pull requests. This can -be to show support for a feature that you're really interested in having, or to -point out possible red flags or downsides to the change. +Comments are welcome on proposal tracking issues and RFC pull requests. This can be to show support for a feature that +you're really interested in having, or to point out possible red flags or downsides to the change. - [Creating new proposals](#what-the-process-is) -If a feature or change you think is needed hasn't been proposed, create a new -tracking issue. +If a feature or change you think is needed hasn't been proposed, create a new tracking issue. - [Writing RFC documents](#what-the-process-is) -If you're interested in helping to design an existing proposal, comment on the -tracking issue and get started on an RFC document. +If you're interested in helping to design an existing proposal, comment on the tracking issue and get started on an RFC +document. - [Implementing proposals that are ready](#implementing-an-rfc) -Once a proposal has been reviewed and is ready, contributions to its -implementation are greatly appreciated. We try to estimate the effort needed to -implement a proposal. If you're looking for a good introductory project, [look -for proposals that are labeled "ready" and "effort/small".](https://github.com/awslabs/aws-cdk-rfcs/issues?utf8=%E2%9C%93&q=is%3Aopen+label%3Astatus%2Fready+label%3Aeffort%2Fsmall) +Once a proposal has been reviewed and is ready, contributions to its implementation are greatly appreciated. We try to +estimate the effort needed to implement a proposal. If you're looking for a good introductory project, +[look for proposals that are labeled "ready" and "effort/small".](https://github.com/awslabs/aws-cdk-rfcs/issues?utf8=%E2%9C%93&q=is%3Aopen+label%3Astatus%2Fready+label%3Aeffort%2Fsmall) ## When to follow this process -You should consider using this process if you intend to make "substantial" -changes to [AWS CDK](https://github.com/aws/aws-cdk), -[JSII](https://github.com/aws/jsii), or related tools. Some examples that would -benefit from an RFC are: +You should consider using this process if you intend to make "substantial" changes to +[AWS CDK](https://github.com/aws/aws-cdk), [JSII](https://github.com/aws/jsii), or related tools. Some examples that +would benefit from an RFC are: - Any change to existing APIs that could break existing code. - The removal of existing features or public APIs. -- The introduction of new idiomatic usage or conventions, even if they do not - include code changes to CDK or JSII themselves. +- The introduction of new idiomatic usage or conventions, even if they do not include code changes to CDK or JSII + themselves. - Changes to the documented contribution workflow. - Features that cross multiple construct libraries. - Additions or changes to framework capabilities. -- Additions or changes to formal specifications like cloud assembly, tree.json, - JSII, etc. +- Additions or changes to formal specifications like cloud assembly, tree.json, JSII, etc. -The RFC process is a great opportunity to get more eyeballs on your proposal -before it becomes a part of a released version of CDK/JSII. Quite often, even -proposals that seem "obvious" can be significantly improved once a wider group -of interested people have a chance to weigh in. +The RFC process is a great opportunity to get more eyeballs on your proposal before it becomes a part of a released +version of CDK/JSII. Quite often, even proposals that seem "obvious" can be significantly improved once a wider group of +interested people have a chance to weigh in. -The RFC process can also be helpful to encourage discussions about a proposed -feature as it is being designed, and incorporate important constraints into the -design while it's easier to change, before the design has been fully +The RFC process can also be helpful to encourage discussions about a proposed feature as it is being designed, and +incorporate important constraints into the design while it's easier to change, before the design has been fully implemented. -If you submit a pull request to implement a new major feature without going -through the RFC process, it may be closed with a polite request to submit an RFC -first. +If you submit a pull request to implement a new major feature without going through the RFC process, it may be closed +with a polite request to submit an RFC first. Some changes do not require an RFC: - Bugfixes for known issues. -- Additions only likely to be _noticed by_ other developers of CDK/JSII, invisible - to users of CDK/JSII. -- Additions of missing L1 or L2 constructs. Unless the service and/or constructs - are especially complex or intentionally diverge from existing api design best - practices. +- Additions only likely to be _noticed by_ other developers of CDK/JSII, invisible to users of CDK/JSII. +- Additions of missing L1 or L2 constructs. Unless the service and/or constructs are especially complex or intentionally + diverge from existing api design best practices. -If you're not sure whether your change requires an RFC, feel free to create an -issue and ask. +If you're not sure whether your change requires an RFC, feel free to create an issue and ask. ## What the process is -In short, to get a major feature added to CDK/JSII, one usually first gets the -RFC merged into the RFC repo as a markdown file. At that point the RFC is -'ready' and may be implemented with the goal of eventual inclusion into +In short, to get a major feature added to CDK/JSII, one usually first gets the RFC merged into the RFC repo as a +markdown file. At that point the RFC is 'ready' and may be implemented with the goal of eventual inclusion into CDK/JSII. -- [Create a tracking issue](https://github.com/awslabs/aws-cdk-rfcs/issues/new?template=tracking-issue.md) - for the proposed feature if one doesn't already exist. Use the tracking issue - template as a guide. If a tracking issue already exists, make sure to update - it and assign it to let others know you're working on a proposal. +- [Create a tracking issue](https://github.com/awslabs/aws-cdk-rfcs/issues/new?template=tracking-issue.md) for the + proposed feature if one doesn't already exist. Use the tracking issue template as a guide. If a tracking issue already + exists, make sure to update it and assign it to let others know you're working on a proposal. - Fork the [RFC repo](https://github.com/awslabs/aws-cdk-rfcs). -- Copy `0000-template.md` to `text/-.md` where is the - tracking issue number and `` is the rfc title. -- Fill in the RFC. Put care into the details: **We welcome all honest efforts to - contribute.**. -- Submit a pull request with the title `RFC: ` where <rfc#> is the - tracking issue number and title is the name of the proposal. As a pull request - the RFC will receive design feedback from the core team and the larger +- Copy `0000-template.md` to `text/<rfc#>-<my-feature>.md` where <rfc#> is the tracking issue number and `<my-feature>` + is the rfc title. +- Fill in the RFC. Put care into the details: **We welcome all honest efforts to contribute.**. +- Submit a pull request with the title `RFC: <rfc#> <title>` where <rfc#> is the tracking issue number and title is the + name of the proposal. As a pull request the RFC will receive design feedback from the core team and the larger community, and the author should be prepared to make revisions in response. - Update the tracking issue with a link to the RFC PR. -- Build consensus and integrate feedback. RFCs that have broad support are much - more likely to make progress than those that don't receive any comments. -- Eventually, the team will decide whether the RFC is a candidate for inclusion - in CDK/JSII. -- RFCs that are candidates for inclusion in CDK/JSII will enter a "final comment - period" lasting 3 calendar days. The beginning of this period will be signaled - by a team member adding a comment and label on the RFCs pull request. -- An RFC can be modified based upon feedback from the team and community. - Significant modifications may trigger a new final comment period. -- An RFC may be rejected by the team after public discussion has settled and - comments have been made summarizing the rationale for rejection. A member of - the team should then close the RFCs associated pull request. -- An RFC may be accepted at the close of its final comment period. A team member - will merge the RFCs associated pull request, at which point the RFC will - become 'ready'. - -If the submitter is someone from our CDK community (i.e., not core team member), -a core team member will be assigned to 'champion' each proposal. They will -generally be the ones updating the RFCs state in the tracking issue as it moves +- Build consensus and integrate feedback. RFCs that have broad support are much more likely to make progress than those + that don't receive any comments. +- Eventually, the team will decide whether the RFC is a candidate for inclusion in CDK/JSII. +- RFCs that are candidates for inclusion in CDK/JSII will enter a "final comment period" lasting 3 calendar days. The + beginning of this period will be signaled by a team member adding a comment and label on the RFCs pull request. +- An RFC can be modified based upon feedback from the team and community. Significant modifications may trigger a new + final comment period. +- An RFC may be rejected by the team after public discussion has settled and comments have been made summarizing the + rationale for rejection. A member of the team should then close the RFCs associated pull request. +- An RFC may be accepted at the close of its final comment period. A team member will merge the RFCs associated pull + request, at which point the RFC will become 'ready'. + +If the submitter is someone from our CDK community (i.e., not core team member), a core team member will be assigned to +'champion' each proposal. They will generally be the ones updating the RFCs state in the tracking issue as it moves through the process. They can decide when a final comment period is triggered. -On the other hand, if the submitter is a core team member, they will identify -another core team member, with consent, as their 'champion'. The champion would -be the first contact for brainstorming, process and reviews. The core team -would defer to the champion to do the first few rounds of reviews, after which -the rest of the team should be engaged. +On the other hand, if the submitter is a core team member, they will identify another core team member, with consent, as +their 'champion'. The champion would be the first contact for brainstorming, process and reviews. The core team would +defer to the champion to do the first few rounds of reviews, after which the rest of the team should be engaged. ## The RFC Life Cycle @@ -240,60 +213,46 @@ custom_mark10 An RFC flows through the following states. -1. Proposed - A tracking issue has been created with a basic outline of the - proposal. -2. Pending - An RFC document has been written with a detailed design and a PR is - under review. -3. Final Comment Period - A core team member has been assigned to oversee the - proposal and at least 1 core team member has approved the RFC PR. - - An RFC may be reverted or closed during final comment period if a member of - the core team or community raises a previously unforeseen issue that is - cause for concern. +1. Proposed - A tracking issue has been created with a basic outline of the proposal. +2. Pending - An RFC document has been written with a detailed design and a PR is under review. +3. Final Comment Period - A core team member has been assigned to oversee the proposal and at least 1 core team member + has approved the RFC PR. + - An RFC may be reverted or closed during final comment period if a member of the core team or community raises a + previously unforeseen issue that is cause for concern. 4. Ready - Final comment period is complete and the PR is merged. -5. Resolved - The implementation is complete and merged across appropriate - repositories. - -Once an RFC becomes ready, then authors may implement it and submit the feature -as a pull request to the aws-cdk or related repos. Becoming 'ready' is not a -rubber stamp, and in particular still does not mean the feature will ultimately -be merged; it does mean that the core team has agreed to it in principle and are -amenable to merging it. - -Furthermore, the fact that a given RFC has been accepted and is 'ready' implies -nothing about what priority is assigned to its implementation, nor whether -anybody is currently working on it. - -Modifications to RFCs marked 'ready' can be done in followup PRs. We strive to -write each RFC in a manner that it will reflect the final design of the feature; -but the nature of the process means that we cannot expect every merged RFC to -actually reflect what the end result will be at the time of the next major -release; therefore we try to keep each RFC document somewhat in sync with the -feature as planned, tracking such changes via followup pull requests to the -document. +5. Resolved - The implementation is complete and merged across appropriate repositories. + +Once an RFC becomes ready, then authors may implement it and submit the feature as a pull request to the aws-cdk or +related repos. Becoming 'ready' is not a rubber stamp, and in particular still does not mean the feature will ultimately +be merged; it does mean that the core team has agreed to it in principle and are amenable to merging it. + +Furthermore, the fact that a given RFC has been accepted and is 'ready' implies nothing about what priority is assigned +to its implementation, nor whether anybody is currently working on it. + +Modifications to RFCs marked 'ready' can be done in followup PRs. We strive to write each RFC in a manner that it will +reflect the final design of the feature; but the nature of the process means that we cannot expect every merged RFC to +actually reflect what the end result will be at the time of the next major release; therefore we try to keep each RFC +document somewhat in sync with the feature as planned, tracking such changes via followup pull requests to the document. ## Reviewing RFCs -Each week the team will attempt to review some set of open RFC pull requests. -Comments and feedback on proposals in any state of the process are welcome and -encouraged. +Each week the team will attempt to review some set of open RFC pull requests. Comments and feedback on proposals in any +state of the process are welcome and encouraged. -Every RFC that we accept should have a core team champion, who will represent -the feature and its progress. When an RFC is merged, we try to label the -tracking with an estimation of effort required for implementation. These are -general "t-shirt size" estimates e.g. small, medium, large. +Every RFC that we accept should have a core team champion, who will represent the feature and its progress. When an RFC +is merged, we try to label the tracking with an estimation of effort required for implementation. These are general +"t-shirt size" estimates e.g. small, medium, large. ## Implementing an RFC -While the author of an RFC (like any other developer) is welcome to offer an -implementation for review after the RFC has been accepted, they have no -obligation to do so. +While the author of an RFC (like any other developer) is welcome to offer an implementation for review after the RFC has +been accepted, they have no obligation to do so. -If you are interested in working on the implementation for an RFC marked -'ready', but cannot determine if someone else is already working on it, feel -free to ask (e.g. by leaving a comment on the associated tracking issue). +If you are interested in working on the implementation for an RFC marked 'ready', but cannot determine if someone else +is already working on it, feel free to ask (e.g. by leaving a comment on the associated tracking issue). -**AWS CDK's RFC process owes its inspiration to the [Yarn RFC process], [Rust -RFC process], [React RFC process], and [Ember RFC process]** +**AWS CDK's RFC process owes its inspiration to the [Yarn RFC process], [Rust RFC process], [React RFC process], and +[Ember RFC process]** [yarn rfc process]: https://github.com/yarnpkg/rfcs [rust rfc process]: https://github.com/rust-lang/rfcs diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index 55ced3541..1e357462b 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -29,195 +29,95 @@ using the new module structure and make that transition as easy as possible. # Basic Example -### New Module Structure +## New Module Structure _Installing aws-cdk 2.0_ ```bash -npm install aws-cdk aws-cdk-lib +npm install aws-cdk @aws-cdk/stdlib ``` _Importing modules from aws-cdk 2.0_ ```typescript -import { aws_ecs as ecs, aws_lambda as lambda, aws_s3 as s3 } from 'aws-cdk-lib'; +import { aws_ecs as ecs, aws_lambda as lambda, aws_s3 as s3 } from '@aws-cdk/stdlib'; ``` -_Importing experimental constructs from aws-cdk 2.0_ - -```typescript -import { aws_appsync as appsync_experimental } from 'aws-cdk-lib/experimental'; -``` - -# Design Summary +# Scope 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. +- [Removal of All Union Types](https://github.com/aws/aws-cdk/issues/5067) - Replace those with a single type that + translates gracefully in languages that do not support type unions (Java, C#, ...). - [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. - Remove Deprecated APIs - Delete all constructs/methods marked with `@deprecated` flag. -- Separate Experimental Code - Extract experimental APIs into a separate entrypoint. # Detailed Design -## Release Stages - -CDK v2.0 will be released in stages. The stages also dictate if and how the v1 modules continue to be published. - -### 1. Experimental +## Branching Model -A module under the name `monocdk-experiment` is created that re-exports the contents of all of the `@aws-cdk/` -namespaced modules. The version number of `monocdk-experiment` is locked to the version of all other modules in the -monorepo. +### Goals -`monodk-experiment` has no source code of its own. It is a series of build scripts that creates a module that re-exports -all of the code of `@aws-cdk/` packages. The build step peforms these actions: +Since the new release includes breaking changes, it is necessary to fork the codebase. The release strategy should +reduce manual effort needed in order to forward-port new feature work merged into the v1 development branch. It also +tries to minimize the amount of "v2 awareness" that needs to be encoded into the v1 codebase during the transition +period. -1. Build and validate package.json - This verifies that the `monocdk-experiment`'s package.json references all of the - modules under the `@aws-cdk/` namespace. If not, it will add those packages to the list of dependencies. -2. Create build directory - Create a temporary directory will code will be staged for build. -3. Generate `index.ts` - Loop through all directories within the `packages/@aws-cdk` directory of the repository and - copy all source code to the buildd directory. Rexport the contents of the copied module from `index.ts` under a - namespace based on the modules directory name. -4. Generate module `package.json` - Create the package.json for the build of `monocdk-experiment`. This has no - dependencies and includes `constructs` and `@types/node` as devDependencies. -5. Install dependencies - Run `npm install`. -6. Compile with jsii -7. Stage for local consumption - copies the compiled `.js` files from the build directory back to the repository in the - `packages/monocdk-experiment/staging` directory. This allows local modules that depend on `monocdk-experiment` to - build against it. -8. Package - module is packaged as a normal jsii package using `jsii-pacmak` in the repositories packaging step using - `pack.sh`. +### Process Flow -All `@aws-cdk/` namespaced libraries will continue to be published as normal. - -### 2. Pre-release - -`monocdk-experiment` is renamed to `aws-cdk-lib`. The version of this module now becomes v2.0 and is tagged as a -"pre-release" version. This has varying formats for different language targets. - -#### NodeJS - -version number: `2.0.0-beta.1` deploying: `npm publish --tag beta` installing: `npm install aws-cdk-lib@beta` -package.json: - -```sh -"dependencies": { - "aws-cdk-lib": "~2.0.0-beta.1" -} -``` +At the inception of this project, a new branch (which will be referred to as `next` in this document, regardless of the +actual name that will be used) will be created in the GitHub repository. This new branch will get a lightweight +continuous integration set-up to facilitate development iteration on this codebase. This will minimally consist of +validation builds, and could be implemented using GitHub actions. The `next` branch codebase will initially be generated +by a foward-porting tool that copies source from the v1 codebase while applying the following transformations: -> 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`. +- removal of all API elements annotated as `@deprecated` +- re-packaging of all AWS Construct Library modules (most modules namespaced within `@aws-cdk`) into a single package + named `@aws-cdk/stdlib`, including any and all assoaciated tests +- re-writing of all `import` statements referring to AWS Construct Library modules so they refer to `@aws-cdk/stdlib` + instead -#### Java +Once the initial fork has been created, an exclusion list will be added to the forward-porting tool, so that it can be +automatically re-applied by a GitHub action triggered on each new commit pushed to the v1 branch, transparently adding +commits on the `next` branch reflecting new developments on the v1 branch. The exclusion list will contain the modules +that require forking in order to deliver the changes in-scope for the new major version. -version number: `2.0.0-beta-1` pom.xml: - -```xml -<dependencies> - <dependency> - <groupId>software.amazon.awscdk</groupId> - <artifactId>lib</artifactId> - <version>2.0.0-beta-1</version> - </dependency> -</dependencies> -``` - -#### Dotnet - -version number: `2.0.0-beta.1` .csproj: - -```xml - <ItemGroup> - <PackageReference Include="Amazon.CDK.Lib" Version="2.0.0-beta.1" /> - </ItemGroup> -``` - -#### Python - -version numbeer: `2.0b1` requirements.txt: - -``` -aws-cdk.lib==2.0b1 -``` +### Removal of TypeScript type unions -All `@aws-cdk/` namespaced libraries will continue to be published with current `1.x.x` versions. +#### Forking `cfn2ts` -### Stable +The AWS CloudFormation Resources layer (aka: L1 constructs) is generated by the `cfn2ts` tool, and makes +quasi-systematic use of type unions with the following shape: -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. +- the CloudFormation Resource Specification declared type of a property or attribute + - if this type is a collection (list or map), the element type is a type union of similar shape +- the `IResolvable` interface that used the be the only way to represent tokens (deploy-time values) -All `@aws-cdk/` namespaced libraries will continue to be published with current `1.x.x` versions. +The vast majority of those type unions could be replaced by only the CloudFormation Resource Specification declared +type, since there are better mechanisms for encoding tokens directly within the most common types (`string`, `number`, +and collections thereof). Complex property types (structs) are not a concern as CloudFormation only supports scalar +values for references (results of `Fn::GetAtt`, `Ref`, ...). -### v1 Deprecation +The `boolean` type is however problematic as there is no way to encode a token as a boolean. A solution is to introduce +a new `CfnBoolean` type to wrap a literal or token as appropriate. A similar strategy can be used for other types that +cannot natively encode a token. -`@aws-cdk/` namespaced modules will continue to receive non-breaking changes and be released regularly. +#### Cleaning up the AWS Construct Library -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. +The AWS Construct Library is a hand-crafted codebase, in which type unions are not widely used. The few APIs that make +use of type unions will need to be replaced by alternatives that do not use a type union. Since the forward-porting tool +removes any `@deprecated` element from the codebase, a simple way to prepare the `next` release is to proactively +deprecate those APIs while adding a better alternative. -## Major Version Rollout Tooling +In order to facilitate detection, the `jsii` compiler will be modifierd to support a new option that causes a +compilation failure to be thrown when a type union is detected. This will be globally turned on in the `next` branch. A +tool may be provided to inspect jsii assemblies created by the v1 codebase and report any type union present on +hand-written APIs (that is, not those generated by `cfn2ts`). -To aid in this phased release, some features will need to be added to JSII and other cdk dev tools. These features will -help us with rolling out major versions in the future. Whenever a new breaking release occurs, deprecated APIs will be -hidden and feature flags will be reset. When we are going through the next cycle of breaking changes, in this case v3.0, -then code related to deprecated APIs and feature flags introduced during the preceding major version cycle, v1.0 in this -case, can be removed since they no longer will be supported. - -#### [JSII Prerelease Versioning Awareness]() - -In order to support releasing the `aws-cdk-lib` with a prerelease version number, JSII needs to parse the version number -of the module its building and recognize it as a "prerelease" and convert it to whatever format is equivalent in the -target languages package manager. - -#### [JSII Submodule Support](https://github.com/aws/jsii/issues/1286) - -JSII currently doesn't handle namespacing of exports. Support for this will be needed to allow building the -`aws-cdk-lib` module in all of the cdk supported target languages. Though the initial work is complete, some open -questions remain about the scope of this feature. Namely, in order to make migrating to the new module structure as easy -as possible, [namespace renaming]() could potentially allow C#, Python, and Java users to not have to change the -structure of their import statements. - -#### [`aws-cdk-lib` Version Unlocking]() - -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]() - -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: - -An api annotated like so: - -```typescript -/** - * @deprecated-v1 - */ -function myDeprecatedApi() {} -``` - -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 - -In addition, linting rules could be created to disallow code deprecated `x` major versions ago". For example, in CDK we -could disallow APIs deprecated more than 1 major version cycle old. So in version `3.x.x`, we could throw a lint error -and require that this code get removed. - -### [Feature Flag Resetting]() +### Feature Flag Resetting Feature flags introduced during the v1 cycle are not allowed to be toggled within v2. This will require users with apps created before a certain feature flag was introduced, to change their code in order to handle the new behavior if they @@ -229,27 +129,26 @@ cycle, aws-cdk command line interactions should emit an error instructing the us any required code changes. Ideally with some information about the specific behavior changes introduced by the feature flag and links to any documentation to help with migration. -### [Namespace Aware Documentation]() +### Namespace Aware Documentation Currently, CDK doc generation makes some assumptions about the structure of modules. If we were to generate -documentation for the `monocdk-experiment` module with the current doc generation, the left panel of the main -documentation site would list only a single module, that being `monocdk-experiment`. Ideally the structure of the -documentation will remain similar to how it is today, with all of the immediate children of the top level export showing -on the left panel. An exception may have to be made for the contents of the current `@aws-cdk/core` module, since those -will all be exposed at the modules top level. Having all of those take up space on the left navigation panel may -introduce unwanted noise. +documentation for the `@aws-cdk/stdlib` module with the current doc generation, the left panel of the main documentation +site would list only a single module, that being `@aws-cdk/stdlib`. Ideally the structure of the documentation will +remain similar to how it is today, with all of the immediate children of the top level export showing on the left panel. +An exception may have to be made for the contents of the current `@aws-cdk/core` module, since those will all be exposed +at the modules top level. Having all of those take up space on the left navigation panel may introduce unwanted noise. ### Migration Tooling In addition to the above changes to build tools, an effort will be made to provide tooling to make migration for users as easy as possible. -#### [Import Rewriter]() +#### Import Rewriter -A command line tool to change the import statements in an existing cdk application from the old multi-module to the new -single module structure. +##### TypeScript -for example: +A command line tool to change the import statements in an existing cdk application written in TypeScript from the old +multi-module to the new single module structure: ```typescript import { App, Stack } from '@aws-cdk/core'; @@ -257,37 +156,54 @@ import * as s3 from '@aws-cdk/aws-s3'; import { Cluster, Service } from '@aws-cdk/aws-ecs'; ``` -will automatically be changed to: +would automatically be changed to: ```typescript -import { App, Stack } from 'aws-cdk-lib'; -import * as s3 from 'aws-cdk-lib/s3'; -import { Cluster, Service } from 'aws-cdk-lib/ecs'; +import { App, Stack } from '@aws-cdk/stdlib'; +import * as s3 from '@aws-cdk/stdlib/s3'; +import { Cluster, Service } from '@aws-cdk/stdlib/ecs'; ``` -It is not yet known if imports will require change when using other languages. See [namespace renaming]() for more -details regarding that. +##### Other Languages + +CDK applications written in Java and DotNet (C#, F#, ...) will not need to update `import`/`using` statements, as +`jsii-pacmak` will be configured to emit identical package/namespace names as v1. -#### [Migration Guide]() +The Python modules layout generated for `next` could match that of v1, inw hich case no import changes will be +necessary. + +#### Migration Guide A comprehensive guide for migrating cdk apps from v1 to v2 will be added to the aws-cdk documentation. A place for future migration guides will be defined and a markdown document will be written detailing what steps users should take when upgrading to cdk v2. -This guide will detail: +This guide will detail, for each supported programming language: -1. Installing `aws-cdk-lib` and removing `@aws-cdk/` modules. -2. Upgrading version of `aws-cdk` and other toolchain packages to version `2.x`. -3. Rewriting import statements in source code if necessary, and how to use the [import rewriter]() -4. Removing usage of deprecated APIs. +1. Ensuring the migrated application makes no use of `@deprecated` APIs +1. Ensuring the migrated application does not depend on a feature flag + - For each feature flag, how to migrate to the `next` state +1. Replacing dependencies on `@aws-cdk` namespaced modules with `@aws-cdk/stdlin` +1. Upgrading version of `aws-cdk` and other toolchain packages to version `2.x` +1. Updating import statements (where needed) using the [provided tools](#import-rewriter) -- List of APIs being deprecated and links to the suggested alternatives for each. +## Release Cutover -5. Removing references to old feature flags +After sufficient time releasing `next` with a prerelease identifier (`v2.0.0-dev.X`), it will be decided that `next` is +ready for General Availability. The lead up to releasing `2.0.0` is composed of the following high-level steps: -- List of feature flags being removed and strategy for migrating to new behavior for each. +1. Publicly declare the beginning of a Developer Preview phase, and start releasing as `v2.0.0-preview` + - This should include the publishing of a maintenance plan for v1 +1. Dial down automated forward-porting of new v1 changes + - Stop automatically pushing changes to the `next` branch, submit PRs instead + - Encourage users to consider rebasing their PRs to `next` instead of `main` +1. Vet the new release with as much real-world usage as possible, gaining confidence the product is good +1. When ready, make `v2.0.0` Generally Available + - Stop automatically forward-porting changes from v1 to `next` + - Rename the `main` branch to `v1` (updating the base of all existing PRs) + - Rename the `next` branch to `main` (updating the abse of all existing PRs) -### Additional Candidates for Inclusion: +## Additional Candidates for Inclusion: The following are changes whose implementation's have been identified as requiring a breaking change. Inclusion in the v2 release is up for debate. Arguments to include a specific feature should take into account any increase in cost to @@ -295,25 +211,25 @@ the development team required to ship the release, and to users required to migr Though we want to keep both of these costs as low as possible, a breaking release is something that happens relatively infrequently, so the opportunity should be taken to include features determined to have a high payoff to users. -In addition, since the v1 modules will continue to be supported for some time, and the `aws-cdk-lib` package will be +In addition, since the v1 modules will continue to be supported for some time, and the `@aws-cdk/stdlib` package will be made of up these modules, the inclusion of any of these candidate features would need to be implemented in a way that didn't affect the v1 modules. How this would be done has not been determined, but may be affected by the nature of any particular change. -#### Recommended +### Recommended The following are good candidates for inclusion in this major version release -- [Easier Identification of Experimental Modules and APIs](https://github.com/aws/aws-cdk-rfcs/issues/116) +#### [Easier Identification of Experimental Modules and APIs](https://github.com/aws/aws-cdk-rfcs/issues/116) There have been long running discussions about separating experimental APIs into a separate module to make them a more -explicit "opt in" feature. Users would either have to install a different module (i.e. `aws-cdk-lib-exerimental`) or -import from a different entrypoint (`import * as s3 from 'aws-cdk-lib/experimental`). Since this could be performed at -build time and be an optional setting thats turned on or off, it could be introduced in the 2.0 release without +explicit "opt in" feature. Users would either have to install a different module (i.e. `@aws-cdk/stdlib-exerimental`) or +import from a different entrypoint (`import * as s3 from '@aws-cdk/stdlib/experimental`). Since this could be performed +at build time and be an optional setting thats turned on or off, it could be introduced in the 2.0 release without affecting the v1 modules, this seems like an ideal time to implement. The technical details of how to achieve this are yet to be determined. -- [Public S3 Artifacts](https://github.com/aws/aws-cdk-rfcs/issues/39) +#### [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 @@ -322,16 +238,22 @@ be accomplished by packaging said assets, uploading them to S3, and then creatin layers referencing them across all AWS regions. Whether v2 of the cdk could accomplish this without impacting v1 has not been determined. -- [Rename ID Parameter](https://github.com/aws/aws-cdk/issues/3203) +#### [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. -#### Not Recommended +There are other parameter or API names that are known to produce degrated experience for developers in other languages, +including (possibly not limited to): + +- `self` +- `Function` + +### Not Recommended The following require more research to be implemented without causing undue breakage. -- [Unmangled L2 Logical IDs](https://github.com/aws/aws-cdk/issues/1687) +#### [Unmangled L2 Logical IDs](https://github.com/aws/aws-cdk/issues/1687) Changing logical ID generation in any capacity could cost users with existing CDK apps a lot of pain. To deploy their stacks without breaking deployed resources, they may have to change IDs and/or certain property parameters passed to @@ -340,16 +262,7 @@ investigation should work towards the potential to implement this behind a featu an automated way to make sure resources defined in existing stacks will not have their logical IDs changed causing them to be torn down and replaced unexpectedly. -- [Removal of All Union Types](https://github.com/aws/aws-cdk/issues/5067) - -JSII's support for union types currently results in the loss of type information in certain language targets when -passing data between the JSII and target language runtimes. Removing union types from the cdk codebase to improve user -experience in all non-typescript targets would result in breaking some existing public APIs that use them. The current -recommendation is to audit the CDK for all union types and APIs that rely on them. These APIs should be marked -deprecated and new alternatives should be created. The newly deprecated APIs would be removed as part of the normal -major version release process going forward. - -- [Remove Custom Resource Implementation of Fargate Event Target](https://github.com/aws/aws-cdk/issues/3930) +#### [Remove Custom Resource Implementation of Fargate Event Target](https://github.com/aws/aws-cdk/issues/3930) Investigation should take place to discern if this could be changed without breaking the public API and/or existing stack resources. If not, is creating a new construct and deprecating the old one at the top level a viable strategy for @@ -358,23 +271,23 @@ constructs with planned breaking changes going forward? Is it appropriate to dep constructs that are being deprecated to make sure they don't experience interruptions in service? Because of these unknowns, it is unlikely that this will be included in the 2.0 release. -- [Change Logical IDs to Avoid Potential Collisions](https://github.com/aws/aws-cdk/issues/6421) +#### [Change Logical IDs to Avoid Potential Collisions](https://github.com/aws/aws-cdk/issues/6421) Similar to aws/aws-cdk#1687, changing logical ID logic introduces a lot of problems for existing users. Whether `LogicalIds 2.0` can be implemented behind a feature flag should be investigated to avoid breaking existing apps. -- [AliasOptions and VersionOptions should not extend EventInvokeConfigOptions](https://github.com/aws/aws-cdk/issues/6966) +#### [AliasOptions and VersionOptions should not extend EventInvokeConfigOptions](https://github.com/aws/aws-cdk/issues/6966) More information needed. @eladb -- [Remove Support for Docker Assets with Parameters]() +#### [Remove Support for Docker Assets with Parameters]() More information needed. @eladb # Drawbacks The main drawback of this staged release strategy is the complexity we will incur within our build tooling to be more -version aware. Though doing things like selectively including or excluding deprecated APIs based on vurrent version +version aware. Though doing things like selectively including or excluding deprecated APIs based on current version allows us to phase the release of breaking changes without having to maintain a long lived branch for the upcoming release, the potential for bugs in the functionality of these features could have downsides to users. If a deprecated API is removed from a module when it shouldn't be, and that module is published, it will break user's applications. @@ -390,9 +303,9 @@ flags is, as always, of high importance. 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 +1. Update Dependencies - Changing from referencing the old `@aws-cdk/` packages to the new `@aws-cdk/stdlib` package in + the corresponding target language's package manifest (package.json, .sln, pom.xml, setup.py). +1. 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). @@ -439,16 +352,16 @@ The most notable alternative to releasing a new major version, is basically to n The first is not moving forward with the packaging change at all. For the argument against that, see the [MonoCDK RFC](https://github.com/aws/aws-cdk-rfcs/issues/6). -The second is to simply release the new module, `aws-cdk-lib` locked to the same `1.x.x` version that the other modules -are currently locked to. In fact, that is the first stage of the release process, its just under the name +The second is to simply release the new module, `@aws-cdk/stdlib` locked to the same `1.x.x` version that the other +modules are currently locked to. In fact, that is the first stage of the release process, its just under the name `monocdk-experiment`. This was a low cost way for the dev team, contributors, and users to experiment with the new structure before investing too much towards it. Regardless, the point of using this change to push towards a 2.0 release, is that the single package structure is "the -new cdk". Meaning, the long term plan is to only release the `aws-cdk-lib` package and no longer publish the `@aws-cdk/` -namespaced ones. The [MonoCDK RFC](https://github.com/aws/aws-cdk-rfcs/issues/6) has more info on the problems currently -experienced by users caused by the current packaging strategy and these problems will always exist unless we stop -supporting the `@aws-cdk/` packages. +new cdk". Meaning, the long term plan is to only release the `@aws-cdk/stdlib` package and no longer publish the other +`@aws-cdk/` namespaced ones. The [MonoCDK RFC](https://github.com/aws/aws-cdk-rfcs/issues/6) has more info on the +problems currently experienced by users caused by the current packaging strategy and these problems will always exist +unless we stop supporting the `@aws-cdk/` packages. Since we want to eventually supplant the current module structure with the new one, semver says we have to do it with the release of a major version. @@ -457,9 +370,9 @@ the release of a major version. 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 +1. Update Dependencies - Changing from referencing the old `@aws-cdk/` packages to the new `@aws-cdk/stdlib` package in + the corresponding target language's package manifest (package.json, .sln, pom.xml, setup.py). +1. 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). Users may have to make additional code changes when upgrading if they are relying on deprecated APIs or feature flags @@ -472,14 +385,7 @@ The bulk of unresolved questions are listed in the [detailed design](#detailed-d 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. +1. What will be the maintenance plan for v1 once v2 is generally available? # Future Possibilities From bcea1c7df516bf73c9ad4024f2b5b6159f85941f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BC=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier-Muller?= <rmuller@amazon.com> Date: Fri, 3 Jul 2020 16:12:56 +0200 Subject: [PATCH 04/21] significant re-wording / re-working --- text/0079-cdk-2.0.md | 449 ++++++++++++++++++++----------------------- 1 file changed, 213 insertions(+), 236 deletions(-) diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index 1e357462b..2df20f3c9 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -9,16 +9,14 @@ related issue: https://github.com/aws/aws-cdk-rfcs/issues/6 # Summary -CDK v2.0! - -This RFC details the strategy for building and releasing aws-cdk 2.0, in addition to changes to tooling required to -support this strategy. For details on the specific features themselves, see the corresponding RFCs. +This RFC details the strategy for building and releasing v2 of the AWS CDK, in addition to changes to tooling required +to support this strategy. For details on the specific features themselves, refer to the corresponding RFCs. # Motivation 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. +changes require a v2 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). @@ -27,297 +25,280 @@ The core motivation of this proposal is to detail the plan required to release t users referencing the v1 modules. In short, we want to make sure users have plenty of time to transition their code to using the new module structure and make that transition as easy as possible. -# Basic Example - -## New Module Structure - -_Installing aws-cdk 2.0_ - -```bash -npm install aws-cdk @aws-cdk/stdlib -``` - -_Importing modules from aws-cdk 2.0_ - -```typescript -import { aws_ecs as ecs, aws_lambda as lambda, aws_s3 as s3 } from '@aws-cdk/stdlib'; -``` - # Scope -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. -- [Removal of All Union Types](https://github.com/aws/aws-cdk/issues/5067) - Replace those with a single type that - translates gracefully in languages that do not support type unions (Java, C#, ...). -- [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. -- Remove Deprecated APIs - Delete all constructs/methods marked with `@deprecated` flag. +Since this is the first major version release since we announced General Availability of the AWS CDK, we will pay close +attention to which changes are scoped in for this release. The main criteria used to determine whether a change is +suitable for inclusion are: -# Detailed Design - -## Branching Model +- the change _requires_ breaking existing customers of the changed API or feature + - a migration should be possible without incurring replacement of existing resources +- the change addresses a well documented customer pain point +- the change has had the due diligence done: + - implications of the change are well documented + - an implementation strategy is documented -### Goals +## Changes considered for v2 inclusion -Since the new release includes breaking changes, it is necessary to fork the codebase. The release strategy should -reduce manual effort needed in order to forward-port new feature work merged into the v1 development branch. It also -tries to minimize the amount of "v2 awareness" that needs to be encoded into the v1 codebase during the transition -period. +The table below summarizes changes that are being considered for v2: -### Process Flow +| Decision | RFC / Issue | Description | +| -------- | -------------- | ----------------------------------------------------------------------------------- | +| ✅ In | | Remove `@deprecated` APIs from the previous major version | +| ✅ In | [RFC-55] | Reset all feature flags from the previous major version | +| ✅ In | [RFC-6] | Combine all AWS Construct Libraries into a single package | +| 🔬*TBD* | _TBD_ | Remove the _constructs compatibility layer_ in favor of using `constructs` directly | +| 🔬*TBD* | _TBD_ | Remove all `public` usage of TypeScript type unions | +| 🔬*TBD* | [aws-cdk#3203] | Rename parameters, properties and methods that are awkward in other languages | -At the inception of this project, a new branch (which will be referred to as `next` in this document, regardless of the -actual name that will be used) will be created in the GitHub repository. This new branch will get a lightweight -continuous integration set-up to facilitate development iteration on this codebase. This will minimally consist of -validation builds, and could be implemented using GitHub actions. The `next` branch codebase will initially be generated -by a foward-porting tool that copies source from the v1 codebase while applying the following transformations: +[rfc-55]: ./0055-feature-flags.md +[rfc-6]: ./0006-monolothic-packaging.md +[aws-cdk#3203]: https://github.com/aws/aws-cdk/issues/3203 -- removal of all API elements annotated as `@deprecated` -- re-packaging of all AWS Construct Library modules (most modules namespaced within `@aws-cdk`) into a single package - named `@aws-cdk/stdlib`, including any and all assoaciated tests -- re-writing of all `import` statements referring to AWS Construct Library modules so they refer to `@aws-cdk/stdlib` - instead +## Changes excluded from v2 -Once the initial fork has been created, an exclusion list will be added to the forward-porting tool, so that it can be -automatically re-applied by a GitHub action triggered on each new commit pushed to the v1 branch, transparently adding -commits on the `next` branch reflecting new developments on the v1 branch. The exclusion list will contain the modules -that require forking in order to deliver the changes in-scope for the new major version. +### Can be achieved without breaking existing customers -### Removal of TypeScript type unions +| Decision | RFC / Issue | Description | +| -------- | ----------- | -------------------------------------------------------------------------- | +| 🚫 Out | [#39] | Distribute lambda code for bundled custom resources via a public S3 bucket | +| 🚫 Out | [#116] | Easier identification of `@experimental` modules and APIs | -#### Forking `cfn2ts` +[#39]: https://github.com/aws/aws-cdk-rfcs/issues/39 +[#116]: https://github.com/aws/aws-cdk-rfcs/issues/116 -The AWS CloudFormation Resources layer (aka: L1 constructs) is generated by the `cfn2ts` tool, and makes -quasi-systematic use of type unions with the following shape: +### Can be achieved by deprecating the current API, and introducing a new one -- the CloudFormation Resource Specification declared type of a property or attribute - - if this type is a collection (list or map), the element type is a type union of similar shape -- the `IResolvable` interface that used the be the only way to represent tokens (deploy-time values) +| Decision | RFC / Issue | Description | +| -------- | -------------- | ------------------------------------------------------------------------------------- | +| 🚫 Out | [aws-cdk#3930] | Remove custom-resource based implementation of the Fargate event target | +| 🚫 Out | [aws-cdk#6966] | Decouple lambda's `AliasOptions` and `VersionOptions` from `EventInvokeConfigOptions` | +| 🚫 Out | _N/A_ | Remove support for Docker assets with parameters | -The vast majority of those type unions could be replaced by only the CloudFormation Resource Specification declared -type, since there are better mechanisms for encoding tokens directly within the most common types (`string`, `number`, -and collections thereof). Complex property types (structs) are not a concern as CloudFormation only supports scalar -values for references (results of `Fn::GetAtt`, `Ref`, ...). +[aws-cdk#3930]: https://github.com/aws/aws-cdk/issues/3930 +[aws-cdk#6966]: https://github.com/aws/aws-cdk/issues/6966 -The `boolean` type is however problematic as there is no way to encode a token as a boolean. A solution is to introduce -a new `CfnBoolean` type to wrap a literal or token as appropriate. A similar strategy can be used for other types that -cannot natively encode a token. +### Might force customers to replace existing infrastructure -#### Cleaning up the AWS Construct Library +| Decision | RFC / Issue | Description | +| -------- | -------------- | --------------------------------------------------------------------- | +| 🚫 Out | [aws-cdk#1687] | Un-mangle logical IDs generated for high-level (a.k.a. L2) constructs | +| 🚫 Out | [aws-cdk#6421] | Change logical ID attribution to avoid potential collisions | -The AWS Construct Library is a hand-crafted codebase, in which type unions are not widely used. The few APIs that make -use of type unions will need to be replaced by alternatives that do not use a type union. Since the forward-porting tool -removes any `@deprecated` element from the codebase, a simple way to prepare the `next` release is to proactively -deprecate those APIs while adding a better alternative. +[aws-cdk#1687]: https://github.com/aws/aws-cdk/issues/1687 +[aws-cdk#6421]: https://github.com/aws/aws-cdk/issues/6421 -In order to facilitate detection, the `jsii` compiler will be modifierd to support a new option that causes a -compilation failure to be thrown when a type union is detected. This will be globally turned on in the `next` branch. A -tool may be provided to inspect jsii assemblies created by the v1 codebase and report any type union present on -hand-written APIs (that is, not those generated by `cfn2ts`). +# Detailed Design -### Feature Flag Resetting +## Overview -Feature flags introduced during the v1 cycle are not allowed to be toggled within v2. This will require users with apps -created before a certain feature flag was introduced, to change their code in order to handle the new behavior if they -haven't already. +The development and release of v2 will be done in several key steps, detailed in the following sections: -The CDK should enforce this and ideally also be version aware. If a user has a feature flag configured in their -`cdk.context` file that is no longer configurable, due to its introduction being during the previous major version -cycle, aws-cdk command line interactions should emit an error instructing the user to remove the feature flag and make -any required code changes. Ideally with some information about the specific behavior changes introduced by the feature -flag and links to any documentation to help with migration. +1. [Create a v2 development branch by forking v1](#forking-v2-out-of-v1) +1. [Make the necessary code changes to implement all features scoped in for v2](#feature-implementation) +1. [Prepare documentation updates](#documentation-updates) +1. [Publish and advertise _experimental_ pre-releases to the usual package registries](#prerelease-publishing) +1. [Perform miscelaneous construct library maintenance tasks](#construct-library-maintenance-tasks) +1. [Announce developer preview and document v1 maintenance plan](#developer-preview) +1. [Listen to customer feedback and adjust as needed](#feedback-phase) +1. [Announce General Availability](#general-availability) +1. [Clean up dead code](#clean-up) +1. [Monitor adoption of the new version](#monitoring-adoption) +1. [Announce End-of-Life for v1](#v1-end-of-life) -### Namespace Aware Documentation +## Forking v2 out of v1 -Currently, CDK doc generation makes some assumptions about the structure of modules. If we were to generate -documentation for the `@aws-cdk/stdlib` module with the current doc generation, the left panel of the main documentation -site would list only a single module, that being `@aws-cdk/stdlib`. Ideally the structure of the documentation will -remain similar to how it is today, with all of the immediate children of the top level export showing on the left panel. -An exception may have to be made for the contents of the current `@aws-cdk/core` module, since those will all be exposed -at the modules top level. Having all of those take up space on the left navigation panel may introduce unwanted noise. +The forking point will be achieved by cutting a new `next` branch from the current tip of the `master` branch. The +repository-wide `version` configuration will be updated to `2.0.0-alpha` (the pre-release identifier could be +different). A continuous integration pipeline will be configured on this new branch, so that pull requests can be +automatically validated. -### Migration Tooling +As long as the codebases have not diverged too much, it should be possible to continue forward-porting new developments +on top of the `next` branch by simply cherry-picking new commits from the `master` branch. Alternatively, it might be +possible to simply periodically merge `master` into `next`. -In addition to the above changes to build tools, an effort will be made to provide tooling to make migration for users -as easy as possible. +As the codebases grow further appart, manual work may be required in order to forward-port feature work merged in +`master`. As a consequence we will strive to keep divergences to a minimum for as long as possible. -#### Import Rewriter +## Feature Implementation -##### TypeScript +This section provides detailed plans for implementing the features that were scoped in for this new major version. -A command line tool to change the import statements in an existing cdk application written in TypeScript from the old -multi-module to the new single module structure: +### Removal of `@deprecated` APIs -```typescript -import { App, Stack } from '@aws-cdk/core'; -import * as s3 from '@aws-cdk/aws-s3'; -import { Cluster, Service } from '@aws-cdk/aws-ecs'; -``` +The definition of `@deprecated` in the CDK specifies that annotated APIs will be removed in the next major version +release. Consequently, we will systematically remove all `@deprecated` APIs from the codebase upon cutting a new major +version. -would automatically be changed to: +This task is expected to be easy to carry out by hand. Searching the codebase for `@deprecated` and deleting the +annotated code, as well as any private function that is no longer used. In the event non-`@deprecated` code is found to +depend on `@deprecated` code, the implementation in `master` will be fixed to no longer defer into the `@deprecated` +feature, and that fix will be forward-ported into the `next` branch in the exact same way that other changes are. -```typescript -import { App, Stack } from '@aws-cdk/stdlib'; -import * as s3 from '@aws-cdk/stdlib/s3'; -import { Cluster, Service } from '@aws-cdk/stdlib/ecs'; -``` +### Resetting v1 feature flags -##### Other Languages +When developing new behaviors that are incompatible with previous ones, feature flags were introduced to allow customers +control of when they migrate over to the _new behavior_. However, when a new major version release is issued, the _new +behavior_ becomes the _only behavior_. -CDK applications written in Java and DotNet (C#, F#, ...) will not need to update `import`/`using` statements, as -`jsii-pacmak` will be configured to emit identical package/namespace names as v1. +In order to reduce the codebase divergence between `master` and `next` (in order to minimize the amount of manual work +involved in forward-porting features on `next`), existing feature flags must be made version-aware, such that they are +forcefully enabled when the current version is greater then `2.0.0-0`. -The Python modules layout generated for `next` could match that of v1, inw hich case no import changes will be -necessary. +The actual removal of code paths that support the _old behavior_ will be deferred to _after_ the new major version has +reached _General Availability_. -#### Migration Guide +### Monolithic Packaging -A comprehensive guide for migrating cdk apps from v1 to v2 will be added to the aws-cdk documentation. A place for -future migration guides will be defined and a markdown document will be written detailing what steps users should take -when upgrading to cdk v2. +The AWS Construct Library will be released as a single artifact, instead of a collection of more than 100 libraries. The +`monocdk-experiment` package has the tools necessary to re-package the existing _hypermodular_ libraries into a single +packaging. Re-using that same process will allow keeping the difference between `master` and `next` as constrained as +possible (reducing the need for manual intervention in forward-porting features). -This guide will detail, for each supported programming language: +Consequently, the `monocdk-experiment` package will be renamed so that it is published and advertised as +`@aws-cdk/stdlib` on the `master` branch. Availability of this library as part of CDK v1 is going to provide customers +with a stepping stone to begin migrating their applications to CDK v2. -1. Ensuring the migrated application makes no use of `@deprecated` APIs -1. Ensuring the migrated application does not depend on a feature flag - - For each feature flag, how to migrate to the `next` state -1. Replacing dependencies on `@aws-cdk` namespaced modules with `@aws-cdk/stdlin` -1. Upgrading version of `aws-cdk` and other toolchain packages to version `2.x` -1. Updating import statements (where needed) using the [provided tools](#import-rewriter) +Additionally, all modules that are re-packaged as part of `@aws-cdk/stdlib` will be marked as `"private": true` in the +`next` branch, making these available _only_ via `@aws-cdk/stdlib` in CDK v2. -## Release Cutover +## Documentation Updates -After sufficient time releasing `next` with a prerelease identifier (`v2.0.0-dev.X`), it will be decided that `next` is -ready for General Availability. The lead up to releasing `2.0.0` is composed of the following high-level steps: +Before formally announcing the availability of CDK v2 for early adopters, a documentation source must be availble to +facilitate use of the new repository. The minimum bar should be availability of an API reference documentation for the +v2 codebase that is usable. -1. Publicly declare the beginning of a Developer Preview phase, and start releasing as `v2.0.0-preview` - - This should include the publishing of a maintenance plan for v1 -1. Dial down automated forward-porting of new v1 changes - - Stop automatically pushing changes to the `next` branch, submit PRs instead - - Encourage users to consider rebasing their PRs to `next` instead of `main` -1. Vet the new release with as much real-world usage as possible, gaining confidence the product is good -1. When ready, make `v2.0.0` Generally Available - - Stop automatically forward-porting changes from v1 to `next` - - Rename the `main` branch to `v1` (updating the base of all existing PRs) - - Rename the `next` branch to `main` (updating the abse of all existing PRs) +At the same time, the work to update the [AWS CDK User Guide] should be scoped and planned out. The updates to the User +Guide must also include a migration guide to help developers move from CDK v1 over to v2. Special attention will be +spent in ensuring the v2 release notes contain a clear and accurate summary of breaking changes and how users should +update their applications. -## Additional Candidates for Inclusion: +[aws cdk user guide]: https://docs.aws.amazon.com/cdk/latest/guide/home.html -The following are changes whose implementation's have been identified as requiring a breaking change. Inclusion in the -v2 release is up for debate. Arguments to include a specific feature should take into account any increase in cost to -the development team required to ship the release, and to users required to migrate their apps to the new version. -Though we want to keep both of these costs as low as possible, a breaking release is something that happens relatively -infrequently, so the opportunity should be taken to include features determined to have a high payoff to users. +## Prerelease Publishing -In addition, since the v1 modules will continue to be supported for some time, and the `@aws-cdk/stdlib` package will be -made of up these modules, the inclusion of any of these candidate features would need to be implemented in a way that -didn't affect the v1 modules. How this would be done has not been determined, but may be affected by the nature of any -particular change. +Once sufficient documentation is in place, and the framework-level changes have been implemented and integration tested, +we will be able to start promoting the upcoming new release and point early adopters to experimental builds of CDK v2. +This will allow gathering early feedback on the updated experience. -### Recommended +A prerelease announcement will be published, formally announcing our plan to release AWS CDK v2 in the near future. This +prerelease announcement should at least mention the following elements: -The following are good candidates for inclusion in this major version release +- A provisional list of breaking changes expected to be made to the _AWS Construct Library_ (`@aws-cdk/stdlib`) APIs + during the [Construct Library Maintenance Tasks](#construct-library-maintenance-tasks) phase +- A finalized proposal for the CDK [v1 maintenance plan](#ongoing-maintenance-plan), and a call for developers to + provide feedback on that +- A minimal migration guide for bravehearts who are inclined to try and migrate their existing (**non-production**) + applications -#### [Easier Identification of Experimental Modules and APIs](https://github.com/aws/aws-cdk-rfcs/issues/116) +## Construct Library Maintenance Tasks -There have been long running discussions about separating experimental APIs into a separate module to make them a more -explicit "opt in" feature. Users would either have to install a different module (i.e. `@aws-cdk/stdlib-exerimental`) or -import from a different entrypoint (`import * as s3 from '@aws-cdk/stdlib/experimental`). Since this could be performed -at build time and be an optional setting thats turned on or off, it could be introduced in the 2.0 release without -affecting the v1 modules, this seems like an ideal time to implement. The technical details of how to achieve this are -yet to be determined. +Now that the v2 framework is in place, _AWS Construct Library_ owners (as well as third party contributors) will be +given some time to perform API-breaking maintenance tasks. The API-breaking changes should be limited to items that were +scoped out during the [Prerelease Publishing](#prerelease-publishing) phase and listed in the prerelease announcepent, +however additional changes can be introduced if there is sufficient justification. All breaking changes (including those +planned in the prerelease announcement) will be documented in the release notes for each subsequent prerelease version, +per the standard process. -#### [Public S3 Artifacts](https://github.com/aws/aws-cdk-rfcs/issues/39) +## Developer Preview -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. +At the end of the [Constrcut Library Maintenance Tasks](#construct-library-maintenance-tasks) window, a moratorium on +breaking changes in v2 will be declared, as the codebase is thoroughly tested and vetted. At the end of the vetting +period, and once known issues have been addressed, CDK v2 can be declared _Developer Preview_. -#### [Rename ID Parameter](https://github.com/aws/aws-cdk/issues/3203) +Once the _Developer Preview_ has been declared, breaking changes will only be allowed if they are motivated by +overwhelming customer feedback or the absence of alternate solutions to fix a well-documented pain point introduced by +v2 changes. -`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. +## Feedback Phase -There are other parameter or API names that are known to produce degrated experience for developers in other languages, -including (possibly not limited to): +During _Developer Preview_, we will keep listening to customer feedback and address bugs as they are discovered. The CDK +[version reporting] dataset will be used to track adoption of the new version. We will encourage customers to provide +feedback on the upcoming new release using a pinned GitHub issue, and possibly other means. -- `self` -- `Function` +[version reporting]: https://docs.aws.amazon.com/cdk/latest/guide/tools.html -### Not Recommended +## General Availability -The following require more research to be implemented without causing undue breakage. +After the _Developer Preview_ has been sufficiently vetted, a timeline for _General Availability_ will be agreed upon by +maintainers. The _General Availability_ checkist includes the following items: -#### [Unmangled L2 Logical IDs](https://github.com/aws/aws-cdk/issues/1687) +- [ ] Documentation + - [ ] API Reference Documentation + - [ ] User Guide + - [ ] Migration Guide + - [ ] Final maintenance plan for v1 +- [ ] Quality Assurance + - [ ] Complete suite of integration tests + - [ ] Examples built and tested against v2 +- [ ] No v1 feature is missing from v2 (unless it was deprecated in v1) -Changing logical ID generation in any capacity could cost users with existing CDK apps a lot of pain. To deploy their -stacks without breaking deployed resources, they may have to change IDs and/or certain property parameters passed to -resource constructor functions. Because of this, the change will not be included in the 2.0 release cycle. Future -investigation should work towards the potential to implement this behind a feature flag and, if possible, provide users -an automated way to make sure resources defined in existing stacks will not have their logical IDs changed causing them -to be torn down and replaced unexpectedly. +Once the criteria have been satisfied, the high-level procedure for officially releasing CDK v2 is: -#### [Remove Custom Resource Implementation of Fargate Event Target](https://github.com/aws/aws-cdk/issues/3930) +1. Create a new `v1` branch from the `master` branch + 1. Configure GitHub branch protection on `v1` as appropriate + 1. Deploy CI/CD infrastructure on top of `v1` +1. Make `next` the new `master` branch: + 1. Force-push `next` on `master` + 1. Delete `next` and all related CI/CD infrastructure +1. Perform a _normal_ release +1. Ceremoniously annouce CDK v2 is _Generally Available_, and repeat the v1 maintenance plan -Investigation should take place to discern if this could be changed without breaking the public API and/or existing -stack resources. If not, is creating a new construct and deprecating the old one at the top level a viable strategy for -constructs with planned breaking changes going forward? Is it appropriate to deprecate a portion of a construct -(constructor properties, etc) that would require resource replacement? Can we guide users through replacement of -constructs that are being deprecated to make sure they don't experience interruptions in service? Because of these -unknowns, it is unlikely that this will be included in the 2.0 release. +## Clean Up -#### [Change Logical IDs to Avoid Potential Collisions](https://github.com/aws/aws-cdk/issues/6421) +Now that the new major version has been declared _Generally Available_, the previous major (`v1`) has entered +_maintenance_ mode. Forward porting is no longer exercised: instead, bug fixes on `master` will be back-ported to `v1` +when necessary. This means `master` can diverge more significantly from `v1` than in earler stages of the process. -Similar to aws/aws-cdk#1687, changing logical ID logic introduces a lot of problems for existing users. Whether -`LogicalIds 2.0` can be implemented behind a feature flag should be investigated to avoid breaking existing apps. +The definition of `v1` feature flags and the code paths supporthing the _old behavior_ of those can be deleted. -#### [AliasOptions and VersionOptions should not extend EventInvokeConfigOptions](https://github.com/aws/aws-cdk/issues/6966) +## Monitoring Adoption -More information needed. @eladb +We will keep an eye on adoption of CDK v2 thanks to the [version reporting] dataset. Should adoption pick up too slowly, +actions will be taken to understand the causes for slow adoption and identify opportunities to provide additional +tooling to remove roadblocks and facilitate migration. -#### [Remove Support for Docker Assets with Parameters]() +[version reporting]: https://docs.aws.amazon.com/cdk/latest/guide/tools.html -More information needed. @eladb +## v1 End-of-Life -# Drawbacks +Once the criteria to trigger end-of-life for v1 (as documented by the v1 maintenance plan) are achieved, back-porting +bug fixes is no longer a concern, and the codebase of the `master` branch can be reorganized so that +`monocdk-experiment`-style repackaging of modules is no longer performed. Instead, the codebase mirrors the release +artifacts. -The main drawback of this staged release strategy is the complexity we will incur within our build tooling to be more -version aware. Though doing things like selectively including or excluding deprecated APIs based on current version -allows us to phase the release of breaking changes without having to maintain a long lived branch for the upcoming -release, the potential for bugs in the functionality of these features could have downsides to users. If a deprecated -API is removed from a module when it shouldn't be, and that module is published, it will break user's applications. -Though this could of course be remedied in a patch release. +# Ongoing Maintenance Plan -If a deprecated API isn't removed from a version that it was inteded to be, and users start relying on the presence of -that API, then by fixing the bug and removing the API in future versions we potentionally introduce breaking changes -that weren't intended by us or expected by the users. +Customers of the CDK must be able to rely on the perenity of major version releases. On the other hand, maintaining +multiple major versions at the same time can be challenging, especially if feature work is expected ot happen on both +branches. Our goal is to minimize the cost of maintaining multiple major versions at the same time, while enabling +customers to migrate to a new major version release at their own pace. -Because of this reason, automated verification of our different builds and the presence/absence of APIs and feature -flags is, as always, of high importance. +To this effect, we define the following maintenance levels for CDK major versions: -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: +- **Active**: This release is being actively developed. It receives new features as well as bug fixes. +- **Maintenance**: These releases are no longer actively developed. Bugs reported against one of these releases will be + handled in the same way, and with the same priority, as bugs reported agaisnt the _Active_ release. New features will + not be added to those releases, unless they are aiming to facilitate migration to the _Active_ release, or + community-developed back-porting of features available in the _Active_ release. +- **Deprecated**: These releases are no longer maintained. Customers are advised to migrate to the _Active_ release as + soon as possible. Only fixes for security-impacting bugs will be added to these releases. +- **End-of-Life**: These release no longer receive any development. Customers are advised to migrate to the _Active_ + release as soon as possible. -1. Update Dependencies - Changing from referencing the old `@aws-cdk/` packages to the new `@aws-cdk/stdlib` package in - the corresponding target language's package manifest (package.json, .sln, pom.xml, setup.py). -1. 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). +A suggested maintenance plan is the following: -Users may have to make additional code changes when upgrading if they are relying on deprecated APIs or feature flags -that are being removed. This cost can be minimized through good documentation and information in the -[migration guide](#migration-guide). +- The latest _Generally Available_ release is always the **Active** one +- When the **Active** release changes, it's predecessor immediately enters **Maintenance** status +- After having been in **Maintenance** status for _6 months_, a release transitions to **Deprecated** status +- **Deprecated** releases that are used by less than _10%_ of active CDK users are eligible for **End-of-Life** + declaration. The **End-of-Life** declaration will be collectively decided by the maintainers. # Rationale and Alternatives ## Rationale -The main motivation for moving forward with a 2.0 release now is the desire to start moving towards the single module +The main motivation for moving forward with a v2 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). @@ -357,7 +338,7 @@ modules are currently locked to. In fact, that is the first stage of the release `monocdk-experiment`. This was a low cost way for the dev team, contributors, and users to experiment with the new structure before investing too much towards it. -Regardless, the point of using this change to push towards a 2.0 release, is that the single package structure is "the +Regardless, the point of using this change to push towards a v2 release, is that the single package structure is "the new cdk". Meaning, the long term plan is to only release the `@aws-cdk/stdlib` package and no longer publish the other `@aws-cdk/` namespaced ones. The [MonoCDK RFC](https://github.com/aws/aws-cdk-rfcs/issues/6) has more info on the problems currently experienced by users caused by the current packaging strategy and these problems will always exist @@ -368,28 +349,24 @@ the release of a major version. # Adoption Strategy -All users will perform the following to adopt cdk v2 +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/stdlib` package in - the corresponding target language's package manifest (package.json, .sln, pom.xml, setup.py). -1. 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). - -Users may have to make additional code changes when upgrading if they are relying on deprecated APIs or feature flags -that are being removed. A [migration guide](#migration-guide) will be written with details about each individual feature -flag and deprecated API that users may need to handle differently when upgrading. - -# Unresolved questions - -The bulk of unresolved questions are listed in the [detailed design](#detailed-design) section. To recap: - -1. What additional features beyond adding the necessary tooling for releasing a major version going forward, should be - included if any? -1. What will be the maintenance plan for v1 once v2 is generally available? + the corresponding target language's package manifest (`package.json`, `.csproj`, `pom.xml`, `setup.py`, etc...). +1. Update Imports - Since the current module structure is being changed in certain languages, import statements in + user's code will need to change accordingly: + - In TypeScript, this can be automated by a tool such as `@monocdk-experiment/import-rewriter` + - In Python, manual replacement of import statements migth be necessary + - In .NET languages (C#, F#, ...) and Java, the namespace structure from CDK v1 will be retained, removing the need + for any code change + +Users will naturally have to make additional changes when upgrading if they are relying on deprecated APIs or _old +behaviors_ from feature flags that are being removed. A [migration guide](#migration-guide) will be written with details +about each individual feature flag and deprecated API that users may need to handle differently when upgrading. # Future Possibilities -As our first major version post 1.0, this sets the tone for others going forward. The 2.0 release is looking to be +As our first major version post v1, this sets the tone for others going forward. The v2 release is looking to be relatively painless for users to adopt. The only code change required, if any at all, should be completely automated. The challenge for the future is to maintain that experience whenever possible, and wherever it isn't, give users plenty of time and warning to change their code and provide details about a reasonable path to do so without interruptions to From 81c68d98f61e03ad5bf9ec4ba2d14bd572578db2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BC=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier-Muller?= <rmuller@amazon.com> Date: Fri, 3 Jul 2020 16:19:55 +0200 Subject: [PATCH 05/21] tidy up scope --- text/0079-cdk-2.0.md | 80 ++++++++++++++++++++++---------------------- 1 file changed, 40 insertions(+), 40 deletions(-) diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index 2df20f3c9..ace60a583 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -40,53 +40,53 @@ suitable for inclusion are: ## Changes considered for v2 inclusion -The table below summarizes changes that are being considered for v2: - -| Decision | RFC / Issue | Description | -| -------- | -------------- | ----------------------------------------------------------------------------------- | -| ✅ In | | Remove `@deprecated` APIs from the previous major version | -| ✅ In | [RFC-55] | Reset all feature flags from the previous major version | -| ✅ In | [RFC-6] | Combine all AWS Construct Libraries into a single package | -| 🔬*TBD* | _TBD_ | Remove the _constructs compatibility layer_ in favor of using `constructs` directly | -| 🔬*TBD* | _TBD_ | Remove all `public` usage of TypeScript type unions | -| 🔬*TBD* | [aws-cdk#3203] | Rename parameters, properties and methods that are awkward in other languages | +- The following changes will be included, or are candidates for inclusion: + + | Decision | RFC / Issue | Description | + | -------- | -------------- | ----------------------------------------------------------------------------------- | + | ✅ In | | Remove `@deprecated` APIs from the previous major version | + | ✅ In | [RFC-55] | Reset all feature flags from the previous major version | + | ✅ In | [RFC-6] | Combine all AWS Construct Libraries into a single package | + | 🔬*TBD* | _TBD_ | Remove the _constructs compatibility layer_ in favor of using `constructs` directly | + | 🔬*TBD* | _TBD_ | Remove all `public` usage of TypeScript type unions | + | 🔬*TBD* | [aws-cdk#3203] | Rename parameters, properties and methods that are awkward in other languages | + +* The following changes were scoped out because a solution is likely to be achievable without breaking existing + customers: + + | Decision | RFC / Issue | Description | + | -------- | ----------- | -------------------------------------------------------------------------- | + | 🚫 Out | [#39] | Distribute lambda code for bundled custom resources via a public S3 bucket | + | 🚫 Out | [#116] | Easier identification of `@experimental` modules and APIs | + +* The following changes were scoped out because they can be achieved by introducing a new, fixed API, while deprecating + the current one. If done _before_ v2 is released, this effectively means `v2` will only retain the new and improved + API: + + | Decision | RFC / Issue | Description | + | -------- | -------------- | ------------------------------------------------------------------------------------- | + | 🚫 Out | [aws-cdk#3930] | Remove custom-resource based implementation of the Fargate event target | + | 🚫 Out | [aws-cdk#6966] | Decouple lambda's `AliasOptions` and `VersionOptions` from `EventInvokeConfigOptions` | + | 🚫 Out | _N/A_ | Remove support for Docker assets with parameters | + +* The following changes were excluded because they would likely make migration of existing applications from v1 to v2 + impossible, as they would likely lead to widespread replacement of existing resources (typically, because a new + logical ID would be assigned to those): + + | Decision | RFC / Issue | Description | + | -------- | -------------- | --------------------------------------------------------------------- | + | 🚫 Out | [aws-cdk#1687] | Un-mangle logical IDs generated for high-level (a.k.a. L2) constructs | + | 🚫 Out | [aws-cdk#6421] | Change logical ID attribution to avoid potential collisions | [rfc-55]: ./0055-feature-flags.md [rfc-6]: ./0006-monolothic-packaging.md -[aws-cdk#3203]: https://github.com/aws/aws-cdk/issues/3203 - -## Changes excluded from v2 - -### Can be achieved without breaking existing customers - -| Decision | RFC / Issue | Description | -| -------- | ----------- | -------------------------------------------------------------------------- | -| 🚫 Out | [#39] | Distribute lambda code for bundled custom resources via a public S3 bucket | -| 🚫 Out | [#116] | Easier identification of `@experimental` modules and APIs | - [#39]: https://github.com/aws/aws-cdk-rfcs/issues/39 [#116]: https://github.com/aws/aws-cdk-rfcs/issues/116 - -### Can be achieved by deprecating the current API, and introducing a new one - -| Decision | RFC / Issue | Description | -| -------- | -------------- | ------------------------------------------------------------------------------------- | -| 🚫 Out | [aws-cdk#3930] | Remove custom-resource based implementation of the Fargate event target | -| 🚫 Out | [aws-cdk#6966] | Decouple lambda's `AliasOptions` and `VersionOptions` from `EventInvokeConfigOptions` | -| 🚫 Out | _N/A_ | Remove support for Docker assets with parameters | - -[aws-cdk#3930]: https://github.com/aws/aws-cdk/issues/3930 -[aws-cdk#6966]: https://github.com/aws/aws-cdk/issues/6966 - -### Might force customers to replace existing infrastructure - -| Decision | RFC / Issue | Description | -| -------- | -------------- | --------------------------------------------------------------------- | -| 🚫 Out | [aws-cdk#1687] | Un-mangle logical IDs generated for high-level (a.k.a. L2) constructs | -| 🚫 Out | [aws-cdk#6421] | Change logical ID attribution to avoid potential collisions | - [aws-cdk#1687]: https://github.com/aws/aws-cdk/issues/1687 +[aws-cdk#3203]: https://github.com/aws/aws-cdk/issues/3203 +[aws-cdk#3930]: https://github.com/aws/aws-cdk/issues/3930 [aws-cdk#6421]: https://github.com/aws/aws-cdk/issues/6421 +[aws-cdk#6966]: https://github.com/aws/aws-cdk/issues/6966 # Detailed Design From 8d116bb46826e7b06ddc9cabbb33243c93017f11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BC=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier-Muller?= <rmuller@amazon.com> Date: Fri, 3 Jul 2020 16:27:19 +0200 Subject: [PATCH 06/21] tune up v1 deprecation --- text/0079-cdk-2.0.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index ace60a583..ead707290 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -104,7 +104,7 @@ The development and release of v2 will be done in several key steps, detailed in 1. [Announce General Availability](#general-availability) 1. [Clean up dead code](#clean-up) 1. [Monitor adoption of the new version](#monitoring-adoption) -1. [Announce End-of-Life for v1](#v1-end-of-life) +1. [Deprecation of v1](#deprecation-of-v1) ## Forking v2 out of v1 @@ -260,12 +260,17 @@ tooling to remove roadblocks and facilitate migration. [version reporting]: https://docs.aws.amazon.com/cdk/latest/guide/tools.html -## v1 End-of-Life +## Deprecation of v1 -Once the criteria to trigger end-of-life for v1 (as documented by the v1 maintenance plan) are achieved, back-porting -bug fixes is no longer a concern, and the codebase of the `master` branch can be reorganized so that -`monocdk-experiment`-style repackaging of modules is no longer performed. Instead, the codebase mirrors the release -artifacts. +Based on the v1 maintenance plan, feature development is to stop on CDK v1, as only bugs reported against CDK v1 are to +be fixed. Back-porting of features is not necessary, although the community is still welcome to back-port features. + +New GitHub labels will be added to differentiate bugs affecting `v1`, `v2` or both. The triaging process will need to be +adjusted to include a determination of whether a bug fix against CDK v1 needs forward-porting to v2 or vice-versa. A +similar provision applies to pull-requests, as only the following should be accepted against v1: + +- Features that facilitate migration to v2 +- Features that are back-ported from v2 # Ongoing Maintenance Plan From 6bce2b9b7012dfde316c8cb89419a791aed1f7de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BC=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier-Muller?= <rmuller@amazon.com> Date: Wed, 8 Jul 2020 11:42:02 +0200 Subject: [PATCH 07/21] align maintenance plan to common practices --- images/MaintenancePolicy.png | Bin 0 -> 45255 bytes text/0079-cdk-2.0.md | 46 ++++++++++++++++++++--------------- 2 files changed, 26 insertions(+), 20 deletions(-) create mode 100644 images/MaintenancePolicy.png diff --git a/images/MaintenancePolicy.png b/images/MaintenancePolicy.png new file mode 100644 index 0000000000000000000000000000000000000000..50b1e245a901a04389a044d9fcd2ede300ac0ac7 GIT binary patch literal 45255 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�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 literal 0 HcmV?d00001 diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index ead707290..febf3baad 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -272,32 +272,38 @@ similar provision applies to pull-requests, as only the following should be acce - Features that facilitate migration to v2 - Features that are back-ported from v2 -# Ongoing Maintenance Plan +# AWS CDK Maintenance Policy Customers of the CDK must be able to rely on the perenity of major version releases. On the other hand, maintaining multiple major versions at the same time can be challenging, especially if feature work is expected ot happen on both branches. Our goal is to minimize the cost of maintaining multiple major versions at the same time, while enabling customers to migrate to a new major version release at their own pace. -To this effect, we define the following maintenance levels for CDK major versions: - -- **Active**: This release is being actively developed. It receives new features as well as bug fixes. -- **Maintenance**: These releases are no longer actively developed. Bugs reported against one of these releases will be - handled in the same way, and with the same priority, as bugs reported agaisnt the _Active_ release. New features will - not be added to those releases, unless they are aiming to facilitate migration to the _Active_ release, or - community-developed back-porting of features available in the _Active_ release. -- **Deprecated**: These releases are no longer maintained. Customers are advised to migrate to the _Active_ release as - soon as possible. Only fixes for security-impacting bugs will be added to these releases. -- **End-of-Life**: These release no longer receive any development. Customers are advised to migrate to the _Active_ - release as soon as possible. - -A suggested maintenance plan is the following: - -- The latest _Generally Available_ release is always the **Active** one -- When the **Active** release changes, it's predecessor immediately enters **Maintenance** status -- After having been in **Maintenance** status for _6 months_, a release transitions to **Deprecated** status -- **Deprecated** releases that are used by less than _10%_ of active CDK users are eligible for **End-of-Life** - declaration. The **End-of-Life** declaration will be collectively decided by the maintainers. +To this effect, we define the following life-cycle stages for libraries and tools (later on referenced generically as +_software_) that are part of the CDK ecosystem: + +- **Developer Preview**: During this phase, software is not supported, should not be used in production environments, + and are meant for early access and feedback purposes only. It is possible for future releases to introduce breaking + changes. Once AWS identifies a release to be a stable product, it may mark it as a _Release Candidate_. _Release + Candidates_ are ready for _General Availability_ unless significant bugs emerge, and will receive full AWS support. +- **Full Support**: During this phase, software is fully supported. AWS will provide regular releases that include new + features, support for new services, API updates for existing services, as well as bug and security fixes. +- **Maintenance Announcement**: AWS will make a public announcement at least 6 months before software enters the + **Maintenance** phase. During this period, software will continue to be fully supported. Typically, this announcement + happens at the same time as the next major version is introduced. +- **Maintenance**: During this phase, AWS limits releases to address critical bug fixes and security issues only. + Software will no longer receive API updates for new or existing services, or be updated to support new regions. The + **Maintenance** phase has a default duration of 12 months, unless otherwise specified as part of the **Maintenance + Announcement**. +- **End-of-Support**: This phase starts at the scheduled end of the **Maintenance** phase. Software that has reached + **End-of-Support** will no longer receive updates or new releases. Previously published releases will continue to be + available via public package managers and the code will remain accessible on GitHub. The GitHub repository may be + archived. Use of software that has reached **End-of-Support** is done at the user's discretion. We recommend users + upgrade to the latest major version (the release in **Full Support** phase). + +Here is a visual illystration of the major version life-cycle (timelines are purely illustrative): + +![Illustration of the Maintenance Policy](../images/MaintenancePolicy.png) # Rationale and Alternatives From 96f3d738bb368f32235ddddb253f5c22bc02fffd Mon Sep 17 00:00:00 2001 From: Romain Marcadier <rmuller@amazon.com> Date: Thu, 9 Jul 2020 10:41:18 +0200 Subject: [PATCH 08/21] Update text/0079-cdk-2.0.md Co-authored-by: Elad Ben-Israel <benisrae@amazon.com> --- text/0079-cdk-2.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index febf3baad..c19cf0c0f 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -195,7 +195,7 @@ prerelease announcement should at least mention the following elements: Now that the v2 framework is in place, _AWS Construct Library_ owners (as well as third party contributors) will be given some time to perform API-breaking maintenance tasks. The API-breaking changes should be limited to items that were -scoped out during the [Prerelease Publishing](#prerelease-publishing) phase and listed in the prerelease announcepent, +scoped out during the [Prerelease Publishing](#prerelease-publishing) phase and listed in the prerelease announcement, however additional changes can be introduced if there is sufficient justification. All breaking changes (including those planned in the prerelease announcement) will be documented in the release notes for each subsequent prerelease version, per the standard process. From 67ea3e6fc2521a67ea02bf4c7f1eea5dd7aa64c3 Mon Sep 17 00:00:00 2001 From: Romain Marcadier <rmuller@amazon.com> Date: Thu, 9 Jul 2020 10:41:33 +0200 Subject: [PATCH 09/21] Update text/0079-cdk-2.0.md Co-authored-by: Elad Ben-Israel <benisrae@amazon.com> --- text/0079-cdk-2.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index c19cf0c0f..dc839a5b5 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -202,7 +202,7 @@ per the standard process. ## Developer Preview -At the end of the [Constrcut Library Maintenance Tasks](#construct-library-maintenance-tasks) window, a moratorium on +At the end of the [Construct Library Maintenance Tasks](#construct-library-maintenance-tasks) window, a moratorium on breaking changes in v2 will be declared, as the codebase is thoroughly tested and vetted. At the end of the vetting period, and once known issues have been addressed, CDK v2 can be declared _Developer Preview_. From 4578b0202bb885f49834e6138ede40f5e04dc379 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BC=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier-Muller?= <rmuller@amazon.com> Date: Fri, 10 Jul 2020 12:21:30 +0200 Subject: [PATCH 10/21] updates --- text/0079-cdk-2.0.md | 30 ++++++++++++++++++------------ 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index dc839a5b5..9222ef96f 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -47,8 +47,9 @@ suitable for inclusion are: | ✅ In | | Remove `@deprecated` APIs from the previous major version | | ✅ In | [RFC-55] | Reset all feature flags from the previous major version | | ✅ In | [RFC-6] | Combine all AWS Construct Libraries into a single package | - | 🔬*TBD* | _TBD_ | Remove the _constructs compatibility layer_ in favor of using `constructs` directly | - | 🔬*TBD* | _TBD_ | Remove all `public` usage of TypeScript type unions | + | 🔬*TBD* | [RFC-192] | Remove the _constructs compatibility layer_ in favor of using `constructs` directly | + | 🔬*TBD* | [RFC-193] | Remove all `public` and `protected` usage of TypeScript type unions | + | 🔬*TBD* | _TBD_ | Generate CloudFormation Resources from the CloudFormation Registry schemas | | 🔬*TBD* | [aws-cdk#3203] | Rename parameters, properties and methods that are awkward in other languages | * The following changes were scoped out because a solution is likely to be achievable without breaking existing @@ -78,8 +79,10 @@ suitable for inclusion are: | 🚫 Out | [aws-cdk#1687] | Un-mangle logical IDs generated for high-level (a.k.a. L2) constructs | | 🚫 Out | [aws-cdk#6421] | Change logical ID attribution to avoid potential collisions | -[rfc-55]: ./0055-feature-flags.md [rfc-6]: ./0006-monolothic-packaging.md +[rfc-55]: ./0055-feature-flags.md +[rfc-192]: https://github.com/aws/aws-cdk-rfcs/issues/192 +[rfc-193]: https://github.com/aws/aws-cdk-rfcs/issues/193 [#39]: https://github.com/aws/aws-cdk-rfcs/issues/39 [#116]: https://github.com/aws/aws-cdk-rfcs/issues/116 [aws-cdk#1687]: https://github.com/aws/aws-cdk/issues/1687 @@ -97,7 +100,7 @@ The development and release of v2 will be done in several key steps, detailed in 1. [Create a v2 development branch by forking v1](#forking-v2-out-of-v1) 1. [Make the necessary code changes to implement all features scoped in for v2](#feature-implementation) 1. [Prepare documentation updates](#documentation-updates) -1. [Publish and advertise _experimental_ pre-releases to the usual package registries](#prerelease-publishing) +1. [Announce availability of an _experimental_ pre-releases to the usual package registries](#prerelease-announcement) 1. [Perform miscelaneous construct library maintenance tasks](#construct-library-maintenance-tasks) 1. [Announce developer preview and document v1 maintenance plan](#developer-preview) 1. [Listen to customer feedback and adjust as needed](#feedback-phase) @@ -111,14 +114,17 @@ The development and release of v2 will be done in several key steps, detailed in The forking point will be achieved by cutting a new `next` branch from the current tip of the `master` branch. The repository-wide `version` configuration will be updated to `2.0.0-alpha` (the pre-release identifier could be different). A continuous integration pipeline will be configured on this new branch, so that pull requests can be -automatically validated. +automatically validated. Releases will be automatically published, however using the `next` distribution tag (or the +equivalent concept in other package registries than npm) instead of `latest`. As long as the codebases have not diverged too much, it should be possible to continue forward-porting new developments on top of the `next` branch by simply cherry-picking new commits from the `master` branch. Alternatively, it might be -possible to simply periodically merge `master` into `next`. +possible to simply periodically merge `master` into `next`. This task can easily be automated. As the codebases grow further appart, manual work may be required in order to forward-port feature work merged in -`master`. As a consequence we will strive to keep divergences to a minimum for as long as possible. +`master`. As a consequence we will strive to keep divergences to a minimum for as long as possible. Someone, for example +the on-call engineer or a rotating member of the squad in charge of v2 implementation, will be in charge of performing +the manual conflict resolution against automatically filed pull requests as needed. ## Feature Implementation @@ -175,7 +181,7 @@ update their applications. [aws cdk user guide]: https://docs.aws.amazon.com/cdk/latest/guide/home.html -## Prerelease Publishing +## Prerelease Announcement Once sufficient documentation is in place, and the framework-level changes have been implemented and integration tested, we will be able to start promoting the upcoming new release and point early adopters to experimental builds of CDK v2. @@ -195,10 +201,10 @@ prerelease announcement should at least mention the following elements: Now that the v2 framework is in place, _AWS Construct Library_ owners (as well as third party contributors) will be given some time to perform API-breaking maintenance tasks. The API-breaking changes should be limited to items that were -scoped out during the [Prerelease Publishing](#prerelease-publishing) phase and listed in the prerelease announcement, -however additional changes can be introduced if there is sufficient justification. All breaking changes (including those -planned in the prerelease announcement) will be documented in the release notes for each subsequent prerelease version, -per the standard process. +scoped out during the [Prerelease Announcement](#prerelease-announcement) phase and listed in the prerelease +announcement, however additional changes can be introduced if there is sufficient justification. All breaking changes +(including those planned in the prerelease announcement) will be documented in the release notes for each subsequent +prerelease version, per the standard process. ## Developer Preview From abe3be4a85eeb38055681cdeb6c21b73ad6325bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BC=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier-Muller?= <rmuller@amazon.com> Date: Tue, 21 Jul 2020 14:11:01 +0200 Subject: [PATCH 11/21] revision --- README.md | 460 +++++++++++++++++++++++-------------------- text/0079-cdk-2.0.md | 53 +++-- 2 files changed, 275 insertions(+), 238 deletions(-) diff --git a/README.md b/README.md index 03e33861a..67455bc70 100644 --- a/README.md +++ b/README.md @@ -1,258 +1,280 @@ # AWS CDK RFCs -This repo is a place to propose and track upcoming changes to [AWS CDK], [jsii], and other related projects. It also is -a great place to learn about the current and future state of the libraries and to discover projects for contribution. +This repo is a place to propose and track major upcoming changes to [AWS CDK], [jsii], and +other related projects. It also is a great place to learn about the current and +future state of the libraries and to discover projects for contribution. -[aws cdk]: https://github.com/aws/aws-cdk +[AWS CDK]: https://github.com/aws/aws-cdk [jsii]: https://github.com/aws/jsii -See [The RFC Life Cycle](#the-rfc-life-cycle) to learn more about the states of existing proposals. +**Jump to**: [What is an RFC?](#what-is-an-rfc) | +[When to submit?](#when-to-submit-an-rfc) | +[RFC Process](#rfc-process) | +[RFC Life Cycle](#the-rfc-life-cycle) <!--BEGIN_TABLE--> - -| \# | Title | Owner | Status | -| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | -------- | -| [110](https://github.com/aws/aws-cdk-rfcs/issues/110) | [CLI Compatibility Strategy](https://github.com/aws/aws-cdk-rfcs/blob/master/text/00110-cli-framework-compatibility-strategy.md) | [@iliapolo](https://github.com/iliapolo) | ready | -| [95](https://github.com/aws/aws-cdk-rfcs/issues/95) | [Cognito Construct Library](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0095-cognito-construct-library) | [@nija-at](https://github.com/nija-at) | ready | -| [92](https://github.com/aws/aws-cdk-rfcs/issues/92) | [CI/CD Asset Publishing](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0092-asset-publishing.md) | [@rix0rrr](https://github.com/rix0rrr) | ready | -| [49](https://github.com/aws/aws-cdk-rfcs/issues/49) | [CI/CD for CDK apps](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0049-continuous-delivery.md) | [@rix0rrr](https://github.com/rix0rrr) | ready | -| [6](https://github.com/aws/aws-cdk-rfcs/issues/6) | [Monolithic Packaging](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0006-monolothic-packaging.md) | [@eladb](https://github.com/eladb) | ready | -| [79](https://github.com/aws/aws-cdk-rfcs/issues/79) | [CDK v2.0](https://github.com/aws/aws-cdk-rfcs/issues/79) | [@RomainMuller](https://github.com/RomainMuller) | pending | -| [60](https://github.com/aws/aws-cdk-rfcs/issues/60) | [Bazel Build System](https://github.com/aws/aws-cdk-rfcs/pull/61) | | pending | -| [139](https://github.com/aws/aws-cdk-rfcs/issues/139) | ["fromLookup" for additional resources](https://github.com/aws/aws-cdk-rfcs/issues/139) | | proposed | -| [127](https://github.com/aws/aws-cdk-rfcs/issues/127) | [CDK to directly reference/import/update an existing stack](https://github.com/aws/aws-cdk-rfcs/issues/127) | | proposed | -| [118](https://github.com/aws/aws-cdk-rfcs/issues/118) | [New CDK Major Version](https://github.com/aws/aws-cdk-rfcs/issues/118) | | proposed | -| [116](https://github.com/aws/aws-cdk-rfcs/issues/116) | [Easier identification of experimental modules](https://github.com/aws/aws-cdk-rfcs/issues/116) | [@rix0rrr](https://github.com/rix0rrr) | proposed | -| [109](https://github.com/aws/aws-cdk-rfcs/issues/109) | [Elasticache L2 Constructs](https://github.com/aws/aws-cdk-rfcs/issues/109) | | proposed | -| [107](https://github.com/aws/aws-cdk-rfcs/issues/107) | [Publish a Construct Library Module Lifecycle document](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0107-construct-library-module-lifecycle.md) | [@ccfife](https://github.com/ccfife) | proposed | -| [87](https://github.com/aws/aws-cdk-rfcs/issues/87) | [On-Demand CFN Resource Generator](https://github.com/aws/aws-cdk-rfcs/issues/87) | | proposed | -| [72](https://github.com/aws/aws-cdk-rfcs/issues/72) | [Stack Policy](https://github.com/aws/aws-cdk-rfcs/issues/72) | | proposed | -| [64](https://github.com/aws/aws-cdk-rfcs/issues/64) | [Garbage Collection for Assets](https://github.com/aws/aws-cdk-rfcs/issues/64) | | proposed | -| [63](https://github.com/aws/aws-cdk-rfcs/issues/63) | [CDK in Secure Environments](https://github.com/aws/aws-cdk-rfcs/issues/63) | | proposed | -| [58](https://github.com/aws/aws-cdk-rfcs/issues/58) | [Improved ergonomics for stack default environment](https://github.com/aws/aws-cdk-rfcs/issues/58) | | proposed | -| [52](https://github.com/aws/aws-cdk-rfcs/issues/52) | [Support resource import](https://github.com/aws/aws-cdk-rfcs/issues/52) | | proposed | -| [51](https://github.com/aws/aws-cdk-rfcs/issues/51) | [Standardize security groups](https://github.com/aws/aws-cdk-rfcs/issues/51) | | proposed | -| [48](https://github.com/aws/aws-cdk-rfcs/issues/48) | [Faster builds](https://github.com/aws/aws-cdk-rfcs/issues/48) | [@rix0rrr](https://github.com/rix0rrr) | proposed | -| [46](https://github.com/aws/aws-cdk-rfcs/issues/46) | [Hooks](https://github.com/aws/aws-cdk-rfcs/issues/46) | | proposed | -| [40](https://github.com/aws/aws-cdk-rfcs/issues/40) | [Stack traces across language boundaries](https://github.com/aws/aws-cdk-rfcs/issues/40) | | proposed | -| [39](https://github.com/aws/aws-cdk-rfcs/issues/39) | [Release public artifacts (lambda layers for custom resources, docker images)](https://github.com/aws/aws-cdk-rfcs/issues/39) | | proposed | -| [35](https://github.com/aws/aws-cdk-rfcs/issues/35) | [Publish construct library guidelines](https://github.com/aws/aws-cdk-rfcs/issues/35) | | proposed | -| [34](https://github.com/aws/aws-cdk-rfcs/issues/34) | [Third-party construct ecosystem](https://github.com/aws/aws-cdk-rfcs/issues/34) | | proposed | -| [32](https://github.com/aws/aws-cdk-rfcs/issues/32) | [App-centric operational experience](https://github.com/aws/aws-cdk-rfcs/issues/32) | | proposed | -| [31](https://github.com/aws/aws-cdk-rfcs/issues/31) | [Integration tests](https://github.com/aws/aws-cdk-rfcs/issues/31) | | proposed | -| [30](https://github.com/aws/aws-cdk-rfcs/issues/30) | [Improve synthesized template output](https://github.com/aws/aws-cdk-rfcs/issues/30) | | proposed | -| [28](https://github.com/aws/aws-cdk-rfcs/issues/28) | [Construct library graduation process](https://github.com/aws/aws-cdk-rfcs/issues/28) | | proposed | -| [27](https://github.com/aws/aws-cdk-rfcs/issues/27) | [200 resource limit tools & guidance](https://github.com/aws/aws-cdk-rfcs/issues/27) | | proposed | -| [26](https://github.com/aws/aws-cdk-rfcs/issues/26) | [Monitoring packs](https://github.com/aws/aws-cdk-rfcs/issues/26) | | proposed | -| [25](https://github.com/aws/aws-cdk-rfcs/issues/25) | [Defaults & configuration policy](https://github.com/aws/aws-cdk-rfcs/issues/25) | | proposed | -| [24](https://github.com/aws/aws-cdk-rfcs/issues/24) | [Resource imports](https://github.com/aws/aws-cdk-rfcs/issues/24) | | proposed | -| [23](https://github.com/aws/aws-cdk-rfcs/issues/23) | [Stateful resource support](https://github.com/aws/aws-cdk-rfcs/issues/23) | | proposed | -| [22](https://github.com/aws/aws-cdk-rfcs/issues/22) | [Cost calculator](https://github.com/aws/aws-cdk-rfcs/issues/22) | | proposed | -| [21](https://github.com/aws/aws-cdk-rfcs/issues/21) | [CDK Explorer Roadmap](https://github.com/aws/aws-cdk-rfcs/issues/21) | | proposed | -| [20](https://github.com/aws/aws-cdk-rfcs/issues/20) | [Security posture summary](https://github.com/aws/aws-cdk-rfcs/issues/20) | | proposed | -| [19](https://github.com/aws/aws-cdk-rfcs/issues/19) | [Introspection API](https://github.com/aws/aws-cdk-rfcs/issues/19) | | proposed | -| [18](https://github.com/aws/aws-cdk-rfcs/issues/18) | [Open context provider framework](https://github.com/aws/aws-cdk-rfcs/issues/18) | | proposed | -| [17](https://github.com/aws/aws-cdk-rfcs/issues/17) | [CLI support for multiple-environments](https://github.com/aws/aws-cdk-rfcs/issues/17) | | proposed | -| [15](https://github.com/aws/aws-cdk-rfcs/issues/15) | [Scaffolding](https://github.com/aws/aws-cdk-rfcs/issues/15) | | proposed | -| [14](https://github.com/aws/aws-cdk-rfcs/issues/14) | [Toolchain 2.0](https://github.com/aws/aws-cdk-rfcs/issues/14) | [@shivlaks](https://github.com/shivlaks) | proposed | -| [13](https://github.com/aws/aws-cdk-rfcs/issues/13) | [Improvements to Reference docs](https://github.com/aws/aws-cdk-rfcs/issues/13) | | proposed | -| [10](https://github.com/aws/aws-cdk-rfcs/issues/10) | [New workshop modules](https://github.com/aws/aws-cdk-rfcs/issues/10) | | proposed | -| [9](https://github.com/aws/aws-cdk-rfcs/issues/9) | [Master developer guide sources in main repo](https://github.com/aws/aws-cdk-rfcs/issues/9) | | proposed | -| [8](https://github.com/aws/aws-cdk-rfcs/issues/8) | [Project structure guidelines](https://github.com/aws/aws-cdk-rfcs/issues/8) | | proposed | -| [7](https://github.com/aws/aws-cdk-rfcs/issues/7) | [Lambda Bundles](https://github.com/aws/aws-cdk-rfcs/issues/7) | | proposed | -| [5](https://github.com/aws/aws-cdk-rfcs/issues/5) | [Security-restricted environments](https://github.com/aws/aws-cdk-rfcs/issues/5) | | proposed | -| [4](https://github.com/aws/aws-cdk-rfcs/issues/4) | [CDK Testing Tools](https://github.com/aws/aws-cdk-rfcs/issues/4) | [@nija-at](https://github.com/nija-at) | proposed | -| [3](https://github.com/aws/aws-cdk-rfcs/issues/3) | [Integrate CLI into Native Modules](https://github.com/aws/aws-cdk-rfcs/issues/3) | | proposed | -| [2](https://github.com/aws/aws-cdk-rfcs/issues/2) | [Migration Paths](https://github.com/aws/aws-cdk-rfcs/issues/2) | | proposed | -| [1](https://github.com/aws/aws-cdk-rfcs/issues/1) | [CDK Watch](https://github.com/aws/aws-cdk-rfcs/issues/1) | | proposed | -| [55](https://github.com/aws/aws-cdk-rfcs/issues/55) | [Feature Flags](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0055-feature-flags.md) | [@eladb](https://github.com/eladb) | resolved | -| [37](https://github.com/aws/aws-cdk-rfcs/issues/37) | [Release from a "release" branch](https://github.com/aws/aws-cdk-rfcs/issues/37) | [@MrArnoldPalmer](https://github.com/MrArnoldPalmer) | resolved | -| [36](https://github.com/aws/aws-cdk-rfcs/issues/36) | [Constructs Programming Model](https://github.com/aws/aws-cdk-rfcs/issues/36) | [@eladb](https://github.com/eladb) | resolved | -| [16](https://github.com/aws/aws-cdk-rfcs/issues/16) | [RFC Process](https://github.com/aws/aws-cdk-rfcs/pull/53) | [@MrArnoldPalmer](https://github.com/MrArnoldPalmer) | resolved | - +\#|Title|Owner|Status +---|-----|-----|------ +[6](https://github.com/aws/aws-cdk-rfcs/issues/6)|[Monolithic Packaging](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0006-monolothic-packaging.md)|[@RomainMuller](https://github.com/RomainMuller)|👷 implementing +[49](https://github.com/aws/aws-cdk-rfcs/issues/49)|[CI/CD for CDK apps](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0049-continuous-delivery.md)|[@rix0rrr](https://github.com/rix0rrr)|👷 implementing +[95](https://github.com/aws/aws-cdk-rfcs/issues/95)|[Cognito Construct Library](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0095-cognito-construct-library)|[@nija-at](https://github.com/nija-at)|👷 implementing +[171](https://github.com/aws/aws-cdk-rfcs/issues/171)|[CloudFront Module Redesign](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0171-cloudfront-redesign.md)|[@njlynch](https://github.com/njlynch)|👷 implementing +[192](https://github.com/aws/aws-cdk-rfcs/issues/192)|[Removal of the "constructs" compatibility layer (v2.0)](https://github.com/aws/aws-cdk-rfcs/pull/195)|[@eladb](https://github.com/eladb)|⏰ final comments +[193](https://github.com/aws/aws-cdk-rfcs/issues/193)|[Fixing of type unions](https://github.com/aws/aws-cdk-rfcs/issues/193)|[@RomainMuller](https://github.com/RomainMuller)|⏰ final comments +[18](https://github.com/aws/aws-cdk-rfcs/issues/18)|[Open context provider framework](https://github.com/aws/aws-cdk-rfcs/pull/167)|[@ddneilson](https://github.com/ddneilson)|✍️ review +[25](https://github.com/aws/aws-cdk-rfcs/issues/25)|[Defaults & configuration policy](https://github.com/aws/aws-cdk-rfcs/issues/25)|[@njlynch](https://github.com/njlynch)|✍️ review +[79](https://github.com/aws/aws-cdk-rfcs/issues/79)|[CDK v2.0](https://github.com/aws/aws-cdk-rfcs/pull/156)|[@RomainMuller](https://github.com/RomainMuller)|✍️ review +[175](https://github.com/aws/aws-cdk-rfcs/issues/175)|[AppSync Mapping Template Object Model](https://github.com/aws/aws-cdk-rfcs/pull/177)|[@MrArnoldPalmer](https://github.com/MrArnoldPalmer)|✍️ review +[1](https://github.com/aws/aws-cdk-rfcs/issues/1)|[CDK Watch](https://github.com/aws/aws-cdk-rfcs/issues/1)||💡 proposed +[2](https://github.com/aws/aws-cdk-rfcs/issues/2)|[Migration Paths](https://github.com/aws/aws-cdk-rfcs/issues/2)||💡 proposed +[3](https://github.com/aws/aws-cdk-rfcs/issues/3)|[Integrate CLI into Native Modules](https://github.com/aws/aws-cdk-rfcs/issues/3)||💡 proposed +[4](https://github.com/aws/aws-cdk-rfcs/issues/4)|[CDK Testing Toolkit](https://github.com/aws/aws-cdk-rfcs/issues/4)|[@nija-at](https://github.com/nija-at)|💡 proposed +[5](https://github.com/aws/aws-cdk-rfcs/issues/5)|[Security-restricted environments](https://github.com/aws/aws-cdk-rfcs/issues/5)||💡 proposed +[7](https://github.com/aws/aws-cdk-rfcs/issues/7)|[Lambda Bundles](https://github.com/aws/aws-cdk-rfcs/issues/7)||💡 proposed +[8](https://github.com/aws/aws-cdk-rfcs/issues/8)|[Project structure guidelines](https://github.com/aws/aws-cdk-rfcs/issues/8)||💡 proposed +[9](https://github.com/aws/aws-cdk-rfcs/issues/9)|[Master developer guide sources in main repo](https://github.com/aws/aws-cdk-rfcs/issues/9)||💡 proposed +[10](https://github.com/aws/aws-cdk-rfcs/issues/10)|[New workshop modules](https://github.com/aws/aws-cdk-rfcs/issues/10)||💡 proposed +[13](https://github.com/aws/aws-cdk-rfcs/issues/13)|[Improvements to Reference docs](https://github.com/aws/aws-cdk-rfcs/issues/13)||💡 proposed +[14](https://github.com/aws/aws-cdk-rfcs/issues/14)|[Toolchain 2.0](https://github.com/aws/aws-cdk-rfcs/issues/14)|[@shivlaks](https://github.com/shivlaks)|💡 proposed +[15](https://github.com/aws/aws-cdk-rfcs/issues/15)|[Scaffolding](https://github.com/aws/aws-cdk-rfcs/issues/15)||💡 proposed +[17](https://github.com/aws/aws-cdk-rfcs/issues/17)|[CLI support for multiple-environments](https://github.com/aws/aws-cdk-rfcs/issues/17)||💡 proposed +[19](https://github.com/aws/aws-cdk-rfcs/issues/19)|[Introspection API](https://github.com/aws/aws-cdk-rfcs/issues/19)||💡 proposed +[20](https://github.com/aws/aws-cdk-rfcs/issues/20)|[Security posture summary](https://github.com/aws/aws-cdk-rfcs/issues/20)||💡 proposed +[21](https://github.com/aws/aws-cdk-rfcs/issues/21)|[CDK Explorer Roadmap](https://github.com/aws/aws-cdk-rfcs/issues/21)||💡 proposed +[22](https://github.com/aws/aws-cdk-rfcs/issues/22)|[Cost calculator](https://github.com/aws/aws-cdk-rfcs/issues/22)||💡 proposed +[23](https://github.com/aws/aws-cdk-rfcs/issues/23)|[Stateful resource support](https://github.com/aws/aws-cdk-rfcs/issues/23)||💡 proposed +[24](https://github.com/aws/aws-cdk-rfcs/issues/24)|[Resource imports](https://github.com/aws/aws-cdk-rfcs/issues/24)||💡 proposed +[26](https://github.com/aws/aws-cdk-rfcs/issues/26)|[Monitoring packs](https://github.com/aws/aws-cdk-rfcs/issues/26)||💡 proposed +[27](https://github.com/aws/aws-cdk-rfcs/issues/27)|[200 resource limit tools & guidance](https://github.com/aws/aws-cdk-rfcs/issues/27)||💡 proposed +[28](https://github.com/aws/aws-cdk-rfcs/issues/28)|[Construct library graduation process](https://github.com/aws/aws-cdk-rfcs/issues/28)||💡 proposed +[30](https://github.com/aws/aws-cdk-rfcs/issues/30)|[Improve synthesized template output](https://github.com/aws/aws-cdk-rfcs/issues/30)||💡 proposed +[31](https://github.com/aws/aws-cdk-rfcs/issues/31)|[Integration tests](https://github.com/aws/aws-cdk-rfcs/issues/31)||💡 proposed +[32](https://github.com/aws/aws-cdk-rfcs/issues/32)|[App-centric operational experience](https://github.com/aws/aws-cdk-rfcs/issues/32)||💡 proposed +[34](https://github.com/aws/aws-cdk-rfcs/issues/34)|[Third-party construct ecosystem](https://github.com/aws/aws-cdk-rfcs/issues/34)||💡 proposed +[35](https://github.com/aws/aws-cdk-rfcs/issues/35)|[Publish construct library guidelines](https://github.com/aws/aws-cdk-rfcs/issues/35)||💡 proposed +[39](https://github.com/aws/aws-cdk-rfcs/issues/39)|[Release public artifacts (lambda layers for custom resources, docker images)](https://github.com/aws/aws-cdk-rfcs/issues/39)||💡 proposed +[40](https://github.com/aws/aws-cdk-rfcs/issues/40)|[Stack traces across language boundaries](https://github.com/aws/aws-cdk-rfcs/issues/40)||💡 proposed +[48](https://github.com/aws/aws-cdk-rfcs/issues/48)|[Faster builds](https://github.com/aws/aws-cdk-rfcs/issues/48)|[@rix0rrr](https://github.com/rix0rrr)|💡 proposed +[51](https://github.com/aws/aws-cdk-rfcs/issues/51)|[Standardize security groups](https://github.com/aws/aws-cdk-rfcs/issues/51)||💡 proposed +[52](https://github.com/aws/aws-cdk-rfcs/issues/52)|[Support resource import](https://github.com/aws/aws-cdk-rfcs/issues/52)||💡 proposed +[58](https://github.com/aws/aws-cdk-rfcs/issues/58)|[Improved ergonomics for stack default environment](https://github.com/aws/aws-cdk-rfcs/issues/58)||💡 proposed +[63](https://github.com/aws/aws-cdk-rfcs/issues/63)|[CDK in Secure Environments](https://github.com/aws/aws-cdk-rfcs/issues/63)||💡 proposed +[64](https://github.com/aws/aws-cdk-rfcs/issues/64)|[Garbage Collection for Assets](https://github.com/aws/aws-cdk-rfcs/issues/64)||💡 proposed +[65](https://github.com/aws/aws-cdk-rfcs/issues/65)|[CDK Code Generation from AWS Console](https://github.com/aws/aws-cdk-rfcs/issues/65)||💡 proposed +[66](https://github.com/aws/aws-cdk-rfcs/issues/66)|[StackSets Support](https://github.com/aws/aws-cdk-rfcs/issues/66)||💡 proposed +[67](https://github.com/aws/aws-cdk-rfcs/issues/67)|[Monitoring Packs](https://github.com/aws/aws-cdk-rfcs/issues/67)||💡 proposed +[69](https://github.com/aws/aws-cdk-rfcs/issues/69)|[One-off "job" Stacks ("auto destruct")](https://github.com/aws/aws-cdk-rfcs/issues/69)||💡 proposed +[70](https://github.com/aws/aws-cdk-rfcs/issues/70)|[Cost Estimation Tools](https://github.com/aws/aws-cdk-rfcs/issues/70)||💡 proposed +[71](https://github.com/aws/aws-cdk-rfcs/issues/71)|[Triggers](https://github.com/aws/aws-cdk-rfcs/issues/71)||💡 proposed +[72](https://github.com/aws/aws-cdk-rfcs/issues/72)|[Stack Policy](https://github.com/aws/aws-cdk-rfcs/issues/72)||💡 proposed +[73](https://github.com/aws/aws-cdk-rfcs/issues/73)|[AWS Resource Model](https://github.com/aws/aws-cdk-rfcs/issues/73)||💡 proposed +[74](https://github.com/aws/aws-cdk-rfcs/issues/74)|[Common API for Resources with Web Addresses](https://github.com/aws/aws-cdk-rfcs/issues/74)||💡 proposed +[77](https://github.com/aws/aws-cdk-rfcs/issues/77)|[On-demand import of CloudFormation Resources from Registry](https://github.com/aws/aws-cdk-rfcs/issues/77)||💡 proposed +[78](https://github.com/aws/aws-cdk-rfcs/issues/78)|[Feature proposal: Workspaces](https://github.com/aws/aws-cdk-rfcs/issues/78)||💡 proposed +[82](https://github.com/aws/aws-cdk-rfcs/issues/82)|[Weak references](https://github.com/aws/aws-cdk-rfcs/issues/82)||💡 proposed +[83](https://github.com/aws/aws-cdk-rfcs/issues/83)|[Global Name Prefix](https://github.com/aws/aws-cdk-rfcs/issues/83)||💡 proposed +[86](https://github.com/aws/aws-cdk-rfcs/issues/86)|[AWS Account Alias Resource](https://github.com/aws/aws-cdk-rfcs/issues/86)||💡 proposed +[116](https://github.com/aws/aws-cdk-rfcs/issues/116)|[Easier identification of experimental modules](https://github.com/aws/aws-cdk-rfcs/issues/116)|[@rix0rrr](https://github.com/rix0rrr)|💡 proposed +[118](https://github.com/aws/aws-cdk-rfcs/issues/118)|[New CDK Major Version](https://github.com/aws/aws-cdk-rfcs/issues/118)||💡 proposed +[127](https://github.com/aws/aws-cdk-rfcs/issues/127)|[CDK to directly reference/import/update an existing stack](https://github.com/aws/aws-cdk-rfcs/issues/127)||💡 proposed +[139](https://github.com/aws/aws-cdk-rfcs/issues/139)|["fromLookup" for additional resources](https://github.com/aws/aws-cdk-rfcs/issues/139)||💡 proposed +[159](https://github.com/aws/aws-cdk-rfcs/issues/159)|[Cross-App Resource Sharing](https://github.com/aws/aws-cdk-rfcs/issues/159)||💡 proposed +[161](https://github.com/aws/aws-cdk-rfcs/issues/161)|[Cross-Region/Account References](https://github.com/aws/aws-cdk-rfcs/issues/161)||💡 proposed +[180](https://github.com/aws/aws-cdk-rfcs/issues/180)|[CustomResources: Allow usage across accounts](https://github.com/aws/aws-cdk-rfcs/issues/180)||💡 proposed +[201](https://github.com/aws/aws-cdk-rfcs/issues/201)|[Construct scope relocation](https://github.com/aws/aws-cdk-rfcs/issues/201)||💡 proposed +[204](https://github.com/aws/aws-cdk-rfcs/issues/204)|[Go language bindings](https://github.com/aws/aws-cdk-rfcs/issues/204)||💡 proposed +[16](https://github.com/aws/aws-cdk-rfcs/issues/16)|[RFC Process](https://github.com/aws/aws-cdk-rfcs/pull/53)|[@MrArnoldPalmer](https://github.com/MrArnoldPalmer)|✅ done +[36](https://github.com/aws/aws-cdk-rfcs/issues/36)|[Constructs Programming Model](https://github.com/aws/aws-cdk-rfcs/issues/36)|[@eladb](https://github.com/eladb)|✅ done +[37](https://github.com/aws/aws-cdk-rfcs/issues/37)|[Release from a "release" branch](https://github.com/aws/aws-cdk-rfcs/issues/37)|[@MrArnoldPalmer](https://github.com/MrArnoldPalmer)|✅ done +[55](https://github.com/aws/aws-cdk-rfcs/issues/55)|[Feature Flags](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0055-feature-flags.md)|[@eladb](https://github.com/eladb)|✅ done +[92](https://github.com/aws/aws-cdk-rfcs/issues/92)|[CI/CD Asset Publishing](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0092-asset-publishing.md)|[@rix0rrr](https://github.com/rix0rrr)|✅ done +[107](https://github.com/aws/aws-cdk-rfcs/issues/107)|[Publish a Construct Library Module Lifecycle document](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0107-construct-library-module-lifecycle.md)|[@ccfife](https://github.com/ccfife)|✅ done +[110](https://github.com/aws/aws-cdk-rfcs/issues/110)|[CLI Compatibility Strategy](https://github.com/aws/aws-cdk-rfcs/blob/master/text/00110-cli-framework-compatibility-strategy.md)|[@iliapolo](https://github.com/iliapolo)|✅ done +[60](https://github.com/aws/aws-cdk-rfcs/issues/60)|[Bazel Build System](https://github.com/aws/aws-cdk-rfcs/pull/61)||👎 rejected +[164](https://github.com/aws/aws-cdk-rfcs/issues/164)|[Construct Library Segments](https://github.com/aws/aws-cdk-rfcs/pull/169)|[@nija-at](https://github.com/nija-at)|👎 rejected +[81](https://github.com/aws/aws-cdk-rfcs/issues/81)|[AWS Landing Zone CDK pattern request](https://github.com/aws/aws-cdk-rfcs/issues/81)||❓unknown +[85](https://github.com/aws/aws-cdk-rfcs/issues/85)|[Cross Account resource import and source account tracking](https://github.com/aws/aws-cdk-rfcs/issues/85)|[@skinny85](https://github.com/skinny85)|❓unknown +[158](https://github.com/aws/aws-cdk-rfcs/issues/158)|[Experiment with Resource Provider in TypeScript](https://github.com/aws/aws-cdk-rfcs/pull/170)||❓unknown +[162](https://github.com/aws/aws-cdk-rfcs/issues/162)|[Simplify working with logical IDs when refactoring CDK code](https://github.com/aws/aws-cdk-rfcs/issues/162)||❓unknown <!--END_TABLE--> -## What does all this mean? - -This document is a lot of information about process thats meant to help guide. It is not a set of rules that need to be -strictly applied. It is designed to help contributors (and thats you!) become more involved with the tools that they -rely on. All efforts to contribute are encouraged and appreciated. - ## What is an RFC? -An RFC is a document that proposes and details a change or addition to the CDK, JSII, and other related tooling. It also -is a process for reviewing and discussing the proposal and tracking its implementation. "Request for Comments" means a -request for discussion and oversight about the future of the CDK and JSII from contributors and users. It is an open -forum for suggestions, questions, and feedback. - -The process is intended to be as lightweight and reasonable as possible for the present circumstances. As usual, we are -trying to let the process be driven by consensus and community norms, not impose more structure than necessary. - -The RFC process itself is subject to changes as dictated by the core team and the community. Proposals can include -proposed changes to the RFC process itself to better serve contributors. - -## Contributions - -Contributions are welcome from anyone in a variety of ways. +An RFC is a document that proposes and details a change or addition to the CDK, +jsii, and other related tooling. It also is a process for reviewing and +discussing the proposal and tracking its implementation. "Request for Comments" +means a request for discussion and oversight about the future of the CDK and +jsii from contributors and users. It is an open forum for suggestions, +questions, and feedback. -- [Reviewing and dicussing existing proposals](#reviewing-rfcs) +The process is intended to be as lightweight and reasonable as possible for the +present circumstances. As usual, we are trying to let the process be driven by +consensus and community norms, not impose more structure than necessary. -Comments are welcome on proposal tracking issues and RFC pull requests. This can be to show support for a feature that -you're really interested in having, or to point out possible red flags or downsides to the change. +The RFC process itself is subject to changes as dictated by the core team and +the community. Proposals can include proposed changes to the RFC process itself +to better serve contributors. -- [Creating new proposals](#what-the-process-is) +## When to submit an RFC? -If a feature or change you think is needed hasn't been proposed, create a new tracking issue. - -- [Writing RFC documents](#what-the-process-is) - -If you're interested in helping to design an existing proposal, comment on the tracking issue and get started on an RFC -document. - -- [Implementing proposals that are ready](#implementing-an-rfc) - -Once a proposal has been reviewed and is ready, contributions to its implementation are greatly appreciated. We try to -estimate the effort needed to implement a proposal. If you're looking for a good introductory project, -[look for proposals that are labeled "ready" and "effort/small".](https://github.com/awslabs/aws-cdk-rfcs/issues?utf8=%E2%9C%93&q=is%3Aopen+label%3Astatus%2Fready+label%3Aeffort%2Fsmall) - -## When to follow this process - -You should consider using this process if you intend to make "substantial" changes to -[AWS CDK](https://github.com/aws/aws-cdk), [JSII](https://github.com/aws/jsii), or related tools. Some examples that -would benefit from an RFC are: +You should consider using this process if you intend to make "substantial" +changes to [AWS CDK](https://github.com/aws/aws-cdk), +[jsii](https://github.com/aws/jsii), or related tools. Some examples that would +benefit from an RFC are: - Any change to existing APIs that could break existing code. - The removal of existing features or public APIs. -- The introduction of new idiomatic usage or conventions, even if they do not include code changes to CDK or JSII - themselves. +- The introduction of new idiomatic usage or conventions, even if they do not + include code changes to CDK or jsii themselves. - Changes to the documented contribution workflow. - Features that cross multiple construct libraries. - Additions or changes to framework capabilities. -- Additions or changes to formal specifications like cloud assembly, tree.json, JSII, etc. +- Additions or changes to formal specifications like cloud assembly, tree.json, + jsii, etc. -The RFC process is a great opportunity to get more eyeballs on your proposal before it becomes a part of a released -version of CDK/JSII. Quite often, even proposals that seem "obvious" can be significantly improved once a wider group of -interested people have a chance to weigh in. +The RFC process is a great opportunity to get more eyeballs on your proposal +before it becomes a part of a released version of CDK/jsii. Quite often, even +proposals that seem "obvious" can be significantly improved once a wider group +of interested people have a chance to weigh in. -The RFC process can also be helpful to encourage discussions about a proposed feature as it is being designed, and -incorporate important constraints into the design while it's easier to change, before the design has been fully +The RFC process can also be helpful to encourage discussions about a proposed +feature as it is being designed, and incorporate important constraints into the +design while it's easier to change, before the design has been fully implemented. -If you submit a pull request to implement a new major feature without going through the RFC process, it may be closed -with a polite request to submit an RFC first. +If you submit a pull request to implement a new major feature without going +through the RFC process, it may be closed with a polite request to submit an RFC +first. Some changes do not require an RFC: - Bugfixes for known issues. -- Additions only likely to be _noticed by_ other developers of CDK/JSII, invisible to users of CDK/JSII. -- Additions of missing L1 or L2 constructs. Unless the service and/or constructs are especially complex or intentionally - diverge from existing api design best practices. - -If you're not sure whether your change requires an RFC, feel free to create an issue and ask. - -## What the process is - -In short, to get a major feature added to CDK/JSII, one usually first gets the RFC merged into the RFC repo as a -markdown file. At that point the RFC is 'ready' and may be implemented with the goal of eventual inclusion into -CDK/JSII. - -- [Create a tracking issue](https://github.com/awslabs/aws-cdk-rfcs/issues/new?template=tracking-issue.md) for the - proposed feature if one doesn't already exist. Use the tracking issue template as a guide. If a tracking issue already - exists, make sure to update it and assign it to let others know you're working on a proposal. -- Fork the [RFC repo](https://github.com/awslabs/aws-cdk-rfcs). -- Copy `0000-template.md` to `text/<rfc#>-<my-feature>.md` where <rfc#> is the tracking issue number and `<my-feature>` - is the rfc title. -- Fill in the RFC. Put care into the details: **We welcome all honest efforts to contribute.**. -- Submit a pull request with the title `RFC: <rfc#> <title>` where <rfc#> is the tracking issue number and title is the - name of the proposal. As a pull request the RFC will receive design feedback from the core team and the larger - community, and the author should be prepared to make revisions in response. - - Update the tracking issue with a link to the RFC PR. -- Build consensus and integrate feedback. RFCs that have broad support are much more likely to make progress than those - that don't receive any comments. -- Eventually, the team will decide whether the RFC is a candidate for inclusion in CDK/JSII. -- RFCs that are candidates for inclusion in CDK/JSII will enter a "final comment period" lasting 3 calendar days. The - beginning of this period will be signaled by a team member adding a comment and label on the RFCs pull request. -- An RFC can be modified based upon feedback from the team and community. Significant modifications may trigger a new - final comment period. -- An RFC may be rejected by the team after public discussion has settled and comments have been made summarizing the - rationale for rejection. A member of the team should then close the RFCs associated pull request. -- An RFC may be accepted at the close of its final comment period. A team member will merge the RFCs associated pull - request, at which point the RFC will become 'ready'. - -If the submitter is someone from our CDK community (i.e., not core team member), a core team member will be assigned to -'champion' each proposal. They will generally be the ones updating the RFCs state in the tracking issue as it moves +- Additions only likely to be _noticed by_ other developers of CDK/jsii, invisible + to users of CDK/jsii. +- Additions of missing L1 or L2 constructs. Unless the service and/or constructs + are especially complex or intentionally diverge from existing api design best + practices. + +If you're not sure whether your change requires an RFC, feel free to create an +issue and ask. + +## RFC Process + +In short, to get a major feature added to CDK/jsii, one usually writes an RFC +as a markdown file and gets it approved and merged into the RFC repo. At that point the RFC is +'approved' and may be implemented into CDK/jsii. + +1. [Create a **tracking + issue**](https://github.com/awslabs/aws-cdk-rfcs/issues/new?template=tracking-issue.md) + for the proposed feature if one doesn't already exist. Use the tracking issue + template as a guide. If a tracking issue already exists, make sure to update + it and assign it to let others know you're working on a proposal. +2. Fork the [RFC repo](https://github.com/awslabs/aws-cdk-rfcs). +3. Copy `0000-template.md` to `text/<rfc#>-<my-feature>.md` where <rfc#> is the + tracking issue number and `<my-feature>` is the rfc title. +4. Fill in the RFC. Put care into the details: **We welcome all honest efforts + to contribute.**. +5. Submit a **pull request** with the title `RFC: ### <title>` where ### is the + tracking issue number and title is the name of the proposal. As a pull + request the RFC will receive design feedback from the core team and the + larger community, and the author should be prepared to make revisions in + response. +6. Update the tracking issue with a link to the RFC PR. +7. **Advertise** your RFC amongst stakeholders via social channels (e.g. + twitter) and your team. Build consensus and integrate feedback. RFCs that + have broad support are much more likely to make progress than those that + don't receive any comments. +8. Eventually, the team will decide whether the RFC is a candidate for inclusion + in CDK/jsii. +9. RFCs that are candidates for inclusion in CDK/jsii will enter a "**final comment + period**" lasting 3 calendar days. The beginning of this period will be signaled + by a team member adding a comment and label on the RFCs pull request. +10. An RFC can be modified based upon feedback from the team and community. + Significant modifications may trigger a new final comment period. An RFC can + also be modified after it has been merged and approved, in which case a new + PR will be submitted with the modification, like any other code. +11. An RFC may be **rejected** by the team after public discussion has settled + and comments have been made summarizing the rationale for rejection. A + member of the team will then close the PR and issue. +12. An RFC may be **accepted** at the close of its final comment period. A team + member will merge the RFCs associated pull request, at which point the RFC + will become 'approved'. +13. At some point, someone will pick up the RFC for implementation. For major + features this usually requires devising a detailed implementation plan. To + that end, submit an **additional PR** on the RFC doc that either fills in + the "Implementation Plan" section or references a separate document or + GitHub Project Board which includes the plan. +14. Once this PR is approved, the RFC will move to the 'implementing' state. + Usually we track implementation using GitHub projects. +15. Once implementation is complete, the RFC moves to 'done', and it's issue is + closed. + +> If the submitter is someone from our CDK community (i.e., not core team member), +a core team member will be assigned to 'shepherd' each proposal. They will +generally be the ones updating the RFCs state in the tracking issue as it moves through the process. They can decide when a final comment period is triggered. +> +> On the other hand, if the submitter is a core team member, they will identify +another core team member, with consent, as their 'shepherd'. The shepherd would +be the first contact for brainstorming, process and reviews. The core team +would defer to the shepherd to do the first few rounds of reviews, after which +the rest of the team should be engaged. -On the other hand, if the submitter is a core team member, they will identify another core team member, with consent, as -their 'champion'. The champion would be the first contact for brainstorming, process and reviews. The core team would -defer to the champion to do the first few rounds of reviews, after which the rest of the team should be engaged. - -## The RFC Life Cycle +## RFC Life Cycle -![rfc-states](https://g.gravizo.com/svg?digraph%20states%20{node%20[shape=ellipse];proposed%20[label%20=%20%22Proposed%22];pending%20[label%20=%20%22Pending%22];fcp%20[label%20=%20%22Final%20Comment%20Period%22];ready%20[label%20=%20%22Ready%22];resolved%20[label%20=%20%22Resolved%22];proposed%20-%3E%20pending%20[label%20=%20%22%20rfc%20pr%20created%22];pending%20-%3E%20pending%20[label%20=%20%22%20revisions%22];pending%20-%3E%20fcp%20[label%20=%20%22core%20team%20approval%20%20%20%20%22];fcp%20-%3E%20pending%20[label%20=%20%22%20revision%20requested%22];fcp%20-%3E%20ready%20[label%20=%20%22%20merged%22];ready%20-%3E%20resolved%20[label%20=%20%22%20implementation%20complete%22];}) +![rfc-states](./images/lifecycle.png) -<!-- for later reference from renderer --> -<details> -custom_mark10 - digraph states { +<!-- +digraph states { node [shape=ellipse]; + edge [color=gray, fontsize=12] + + idea [label = "Idea", shape = plaintext] proposed [label = "Proposed"]; - pending [label = "Pending"]; + review [label = "In Review"]; fcp [label = "Final Comment Period"]; - ready [label = "Ready"]; - resolved [label = "Resolved"]; - proposed -> pending [label = " rfc pr created"]; - pending -> pending [label = " revisions"]; - pending -> fcp [label = "core team approval "]; - fcp -> pending [label = " revision requested"]; - fcp -> ready [label = " merged"]; - ready -> resolved [label = " implementation complete"]; - } -custom_mark10 -</details> - -An RFC flows through the following states. - -1. Proposed - A tracking issue has been created with a basic outline of the proposal. -2. Pending - An RFC document has been written with a detailed design and a PR is under review. -3. Final Comment Period - A core team member has been assigned to oversee the proposal and at least 1 core team member - has approved the RFC PR. - - An RFC may be reverted or closed during final comment period if a member of the core team or community raises a - previously unforeseen issue that is cause for concern. -4. Ready - Final comment period is complete and the PR is merged. -5. Resolved - The implementation is complete and merged across appropriate repositories. - -Once an RFC becomes ready, then authors may implement it and submit the feature as a pull request to the aws-cdk or -related repos. Becoming 'ready' is not a rubber stamp, and in particular still does not mean the feature will ultimately -be merged; it does mean that the core team has agreed to it in principle and are amenable to merging it. - -Furthermore, the fact that a given RFC has been accepted and is 'ready' implies nothing about what priority is assigned -to its implementation, nor whether anybody is currently working on it. - -Modifications to RFCs marked 'ready' can be done in followup PRs. We strive to write each RFC in a manner that it will -reflect the final design of the feature; but the nature of the process means that we cannot expect every merged RFC to -actually reflect what the end result will be at the time of the next major release; therefore we try to keep each RFC -document somewhat in sync with the feature as planned, tracking such changes via followup pull requests to the document. - -## Reviewing RFCs - -Each week the team will attempt to review some set of open RFC pull requests. Comments and feedback on proposals in any -state of the process are welcome and encouraged. - -Every RFC that we accept should have a core team champion, who will represent the feature and its progress. When an RFC -is merged, we try to label the tracking with an estimation of effort required for implementation. These are general -"t-shirt size" estimates e.g. small, medium, large. - -## Implementing an RFC - -While the author of an RFC (like any other developer) is welcome to offer an implementation for review after the RFC has -been accepted, they have no obligation to do so. - -If you are interested in working on the implementation for an RFC marked 'ready', but cannot determine if someone else -is already working on it, feel free to ask (e.g. by leaving a comment on the associated tracking issue). - -**AWS CDK's RFC process owes its inspiration to the [Yarn RFC process], [Rust RFC process], [React RFC process], and -[Ember RFC process]** + approved [label = "Approved"]; + plannning [label = "Planning"]; + implementing [label = "Implementing"]; + done [label = "Done"]; + rejected [label = "Rejected"]; + + idea -> proposed [label = "github issue created"] + proposed -> review [label = "pull request with rfc doc created"]; + review -> review [label = "doc revisions"]; + review -> fcp [label = "shepherd approved"]; + review -> rejected [label = "rejected"]; + fcp -> review [label = "revision requested"]; + fcp -> approved [label = "pull request approved and merged"]; + fcp -> rejected [label = "rfc rejected"]; + approved -> plannning [label = "pull request with implementation plan created"]; + plannning -> implementing [label = "rfc with implementation plan approved and merged"]; + implementing -> done [label = "implementation completed"]; +} +--> + +1. **Proposed** - A tracking issue has been created with a basic outline of the + proposal. +2. **Review** - An RFC document has been written with a detailed design and a PR is + under review. At this point the PR will be assigned a **shepherd** from the core + team. +3. **Final Comment Period** - The shepherd has approved the RFC PR, and announces + that the RFC enters a period for final comments before it will be approved (~1wk). + At this stage, if major issues are raised, the RFC may return to **Review**. +4. **Approved** - The RFC PR is approved and merged to `master`, and the RFC is nonw + ready to be implemented. +5. **Planning** - A PR is created with the **Implementation Plan** section of the RFC. +6. **Implementing** - Implemetation plan is approved and merged and the RFC is actively + being implemented. +7. **Done** - Implementation is complete and merged across appropriate + repositories. +8. **Rejected** - During the review period, the RFC may be rejected and then it will + be marked as such. + +--- + +AWS CDK's RFC process owes its inspiration to the [Yarn RFC process], [Rust +RFC process], [React RFC process], and [Ember RFC process] [yarn rfc process]: https://github.com/yarnpkg/rfcs [rust rfc process]: https://github.com/rust-lang/rfcs diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index 9222ef96f..20ec326f2 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -42,15 +42,12 @@ suitable for inclusion are: - The following changes will be included, or are candidates for inclusion: - | Decision | RFC / Issue | Description | - | -------- | -------------- | ----------------------------------------------------------------------------------- | - | ✅ In | | Remove `@deprecated` APIs from the previous major version | - | ✅ In | [RFC-55] | Reset all feature flags from the previous major version | - | ✅ In | [RFC-6] | Combine all AWS Construct Libraries into a single package | - | 🔬*TBD* | [RFC-192] | Remove the _constructs compatibility layer_ in favor of using `constructs` directly | - | 🔬*TBD* | [RFC-193] | Remove all `public` and `protected` usage of TypeScript type unions | - | 🔬*TBD* | _TBD_ | Generate CloudFormation Resources from the CloudFormation Registry schemas | - | 🔬*TBD* | [aws-cdk#3203] | Rename parameters, properties and methods that are awkward in other languages | + | Decision | RFC / Issue | Description | + | -------- | ----------- | ----------------------------------------------------------------------------------- | + | ✅ In | | Remove `@deprecated` APIs from the previous major version | + | ✅ In | [RFC-55] | Reset all feature flags from the previous major version | + | ✅ In | [RFC-6] | Combine all AWS Construct Libraries into a single package | + | ✅ In | [RFC-192] | Remove the _constructs compatibility layer_ in favor of using `constructs` directly | * The following changes were scoped out because a solution is likely to be achievable without breaking existing customers: @@ -58,6 +55,8 @@ suitable for inclusion are: | Decision | RFC / Issue | Description | | -------- | ----------- | -------------------------------------------------------------------------- | | 🚫 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] | Remove all `public` and `protected` usage of TypeScript type unions | | 🚫 Out | [#116] | Easier identification of `@experimental` modules and APIs | * The following changes were scoped out because they can be achieved by introducing a new, fixed API, while deprecating @@ -79,8 +78,16 @@ suitable for inclusion are: | 🚫 Out | [aws-cdk#1687] | Un-mangle logical IDs generated for high-level (a.k.a. L2) constructs | | 🚫 Out | [aws-cdk#6421] | Change logical ID attribution to avoid potential collisions | +* The following changes were excluded because the problem statement is too ambiguous or the solution not clear enough at + this point: + + | Decision | RFC / Issue | Description | + | -------- | -------------- | ----------------------------------------------------------------------------- | + | 🚫 Out | [aws-cdk#3203] | Rename parameters, properties and methods that are awkward in other languages | + [rfc-6]: ./0006-monolothic-packaging.md [rfc-55]: ./0055-feature-flags.md +[rfc-77]: https://github.com/aws/aws-cdk-rfcs/issues/77 [rfc-192]: https://github.com/aws/aws-cdk-rfcs/issues/192 [rfc-193]: https://github.com/aws/aws-cdk-rfcs/issues/193 [#39]: https://github.com/aws/aws-cdk-rfcs/issues/39 @@ -145,14 +152,21 @@ feature, and that fix will be forward-ported into the `next` branch in the exact When developing new behaviors that are incompatible with previous ones, feature flags were introduced to allow customers control of when they migrate over to the _new behavior_. However, when a new major version release is issued, the _new -behavior_ becomes the _only behavior_. +behavior_ ideally becomes the _only behavior_. + +In certain cases, users may be unable to migrate over to the _new behavior_ of a feature flag without incurring +replacement of resources. Removing ability to toggle the feature off in a new major version would significantly +complicate upgrading applications to the new major version. Feature flags will be critically evaluated, and in cases +where a migration is impossible or difficult, the default state will be changed from disabled to enabled, but users will +retain the ability to disable as needed. In order to reduce the codebase divergence between `master` and `next` (in order to minimize the amount of manual work involved in forward-porting features on `next`), existing feature flags must be made version-aware, such that they are -forcefully enabled when the current version is greater then `2.0.0-0`. +enabled by default (and impossible to disable if a clean and reasonably simple migration is possible) when the current +version is greater then `2.0.0-0`. -The actual removal of code paths that support the _old behavior_ will be deferred to _after_ the new major version has -reached _General Availability_. +The actual removal of code paths that support the _old behavior_ of feature flags that can no longer be disabled will be +deferred to _after_ the new major version has reached _General Availability_. ### Monolithic Packaging @@ -199,12 +213,13 @@ prerelease announcement should at least mention the following elements: ## Construct Library Maintenance Tasks -Now that the v2 framework is in place, _AWS Construct Library_ owners (as well as third party contributors) will be -given some time to perform API-breaking maintenance tasks. The API-breaking changes should be limited to items that were -scoped out during the [Prerelease Announcement](#prerelease-announcement) phase and listed in the prerelease -announcement, however additional changes can be introduced if there is sufficient justification. All breaking changes -(including those planned in the prerelease announcement) will be documented in the release notes for each subsequent -prerelease version, per the standard process. +All breaking changes should be handled in the form of a deprecation in CDK v1. In the event a particular change cannot +be achieved in this way, a limited amount of time will be provided when _AWS Construct Library_ owners (as well as third +party contributors) will be allowed to introduce API-breaking changes in the `next` branch. These should be limited to +items that were identified and documented as part of the [Prerelease Announcement](#prerelease-announcement). Additional +changes can however be introduced if a well documented proposal achieves consensus among the core development team. All +breaking changes (including those planned in the prerelease announcement) will be documented in the release notes for +each subsequent prerelease version, per the standard process. ## Developer Preview From 199b546089125b2ac9a83cc9e7600297e85035bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BC=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier-Muller?= <rmuller@amazon.com> Date: Thu, 23 Jul 2020 15:33:40 +0200 Subject: [PATCH 12/21] fix label of type unions RFC --- text/0079-cdk-2.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index 20ec326f2..bc571def4 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -56,7 +56,7 @@ suitable for inclusion are: | -------- | ----------- | -------------------------------------------------------------------------- | | 🚫 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] | Remove all `public` and `protected` usage of TypeScript type unions | + | 🚫 Out | [RFC-193] | Fix API for TypeScript type unions when used in statically typed languages | | 🚫 Out | [#116] | Easier identification of `@experimental` modules and APIs | * The following changes were scoped out because they can be achieved by introducing a new, fixed API, while deprecating From bb513c799c0ecbec40ed7aa281244544950a5c5a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BC=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier-Muller?= <rmuller@amazon.com> Date: Mon, 27 Jul 2020 13:32:50 +0200 Subject: [PATCH 13/21] go back to aws-cdk-lib --- text/0079-cdk-2.0.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index bc571def4..60ceafa6c 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -175,12 +175,12 @@ The AWS Construct Library will be released as a single artifact, instead of a co packaging. Re-using that same process will allow keeping the difference between `master` and `next` as constrained as possible (reducing the need for manual intervention in forward-porting features). -Consequently, the `monocdk-experiment` package will be renamed so that it is published and advertised as -`@aws-cdk/stdlib` on the `master` branch. Availability of this library as part of CDK v1 is going to provide customers -with a stepping stone to begin migrating their applications to CDK v2. +Consequently, the `monocdk-experiment` package will be renamed so that it is published and advertised as `aws-cdk-lib` +on the `master` branch. Availability of this library as part of CDK v1 is going to provide customers with a stepping +stone to begin migrating their applications to CDK v2. -Additionally, all modules that are re-packaged as part of `@aws-cdk/stdlib` will be marked as `"private": true` in the -`next` branch, making these available _only_ via `@aws-cdk/stdlib` in CDK v2. +Additionally, all modules that are re-packaged as part of `aws-cdk-lib` will be marked as `"private": true` in the +`next` branch, making these available _only_ via `aws-cdk-lib` in CDK v2. ## Documentation Updates @@ -204,8 +204,8 @@ This will allow gathering early feedback on the updated experience. A prerelease announcement will be published, formally announcing our plan to release AWS CDK v2 in the near future. This prerelease announcement should at least mention the following elements: -- A provisional list of breaking changes expected to be made to the _AWS Construct Library_ (`@aws-cdk/stdlib`) APIs - during the [Construct Library Maintenance Tasks](#construct-library-maintenance-tasks) phase +- A provisional list of breaking changes expected to be made to the _AWS Construct Library_ (`aws-cdk-lib`) APIs during + the [Construct Library Maintenance Tasks](#construct-library-maintenance-tasks) phase - A finalized proposal for the CDK [v1 maintenance plan](#ongoing-maintenance-plan), and a call for developers to provide feedback on that - A minimal migration guide for bravehearts who are inclined to try and migrate their existing (**non-production**) @@ -365,13 +365,13 @@ The most notable alternative to releasing a new major version, is basically to n The first is not moving forward with the packaging change at all. For the argument against that, see the [MonoCDK RFC](https://github.com/aws/aws-cdk-rfcs/issues/6). -The second is to simply release the new module, `@aws-cdk/stdlib` locked to the same `1.x.x` version that the other -modules are currently locked to. In fact, that is the first stage of the release process, its just under the name +The second is to simply release the new module, `aws-cdk-lib` locked to the same `1.x.x` version that the other modules +are currently locked to. In fact, that is the first stage of the release process, its just under the name `monocdk-experiment`. This was a low cost way for the dev team, contributors, and users to experiment with the new structure before investing too much towards it. Regardless, the point of using this change to push towards a v2 release, is that the single package structure is "the -new cdk". Meaning, the long term plan is to only release the `@aws-cdk/stdlib` package and no longer publish the other +new cdk". Meaning, the long term plan is to only release the `aws-cdk-lib` package and no longer publish the other `@aws-cdk/` namespaced ones. The [MonoCDK RFC](https://github.com/aws/aws-cdk-rfcs/issues/6) has more info on the problems currently experienced by users caused by the current packaging strategy and these problems will always exist unless we stop supporting the `@aws-cdk/` packages. @@ -383,8 +383,8 @@ the release of a major version. 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/stdlib` package in - the corresponding target language's package manifest (`package.json`, `.csproj`, `pom.xml`, `setup.py`, etc...). +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`, `.csproj`, `pom.xml`, `setup.py`, etc...). 1. Update Imports - Since the current module structure is being changed in certain languages, import statements in user's code will need to change accordingly: - In TypeScript, this can be automated by a tool such as `@monocdk-experiment/import-rewriter` @@ -399,7 +399,7 @@ about each individual feature flag and deprecated API that users may need to han # Future Possibilities As our first major version post v1, this sets the tone for others going forward. The v2 release is looking to be -relatively painless for users to adopt. The only code change required, if any at all, should be completely automated. +relatively painless for users to adopt. The most prevalent code change required, if any at all, should be automatable. The challenge for the future is to maintain that experience whenever possible, and wherever it isn't, give users plenty of time and warning to change their code and provide details about a reasonable path to do so without interruptions to their existing cloud resources. From 30b3802c2b8e4198c41906e64288a16847a46375 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BC=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier-Muller?= <rmuller@amazon.com> Date: Tue, 28 Jul 2020 14:29:07 +0200 Subject: [PATCH 14/21] update with (most of) @eladb feedback --- text/0079-cdk-2.0.md | 256 +++++++++++++++++++++++++++++++++++++++---- 1 file changed, 234 insertions(+), 22 deletions(-) diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index 60ceafa6c..2e8daca2e 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -104,6 +104,7 @@ suitable for inclusion are: The development and release of v2 will be done in several key steps, detailed in the following sections: +1. [Preliminary work in v1](#preliminary-work-in-v1) 1. [Create a v2 development branch by forking v1](#forking-v2-out-of-v1) 1. [Make the necessary code changes to implement all features scoped in for v2](#feature-implementation) 1. [Prepare documentation updates](#documentation-updates) @@ -116,22 +117,73 @@ The development and release of v2 will be done in several key steps, detailed in 1. [Monitor adoption of the new version](#monitoring-adoption) 1. [Deprecation of v1](#deprecation-of-v1) +## Preliminary work in v1 + +In order to minimize the divergence between the `v1` and `v2` codebases, all the work that can be performed directly in +v1 will be front-loaded. This includes all work that can be prepared without breaking existing customers of CDK v1: + +- Proactively deprecating APIs that need to be cleaned up in the v2 release, and introducing new replacement APIs (the + removal of deprecated memebers would thus leave only the new API in v2) +- Work identified in [RFC-192] to be done directly in v1, ahead of the actual removal of the _constructs compatibility + layer_ in v2 +- Making the default state of _feature flags_ version-aware + ## Forking v2 out of v1 -The forking point will be achieved by cutting a new `next` branch from the current tip of the `master` branch. The -repository-wide `version` configuration will be updated to `2.0.0-alpha` (the pre-release identifier could be -different). A continuous integration pipeline will be configured on this new branch, so that pull requests can be -automatically validated. Releases will be automatically published, however using the `next` distribution tag (or the -equivalent concept in other package registries than npm) instead of `latest`. +The forking point will be achieved by cutting a new `next` branch from the current tip of the `master` branch, where the +following changes will be made right away: + +1. the repository-wide `version` configuration will be updated to `2.0.0-alpha` (the pre-release identifier could be + different) +1. all packages in the `@aws-cdk` scope included in the monolithic library bundle (see [Annex 1](#annex-1)) will be + marked `"private": true` in their respective `package.json` file +1. the `monocdk-experiment` package will be renamed to `aws-cdk-lib` + +A continuous integration pipeline will be configured on this new branch, so that pull requests can be automatically +validated. Releases will be automatically published, however using the `next` NPM distribution tag instead of `latest`. + +> Other package managers we target (NuGet, Maven Central, PyPI) do not have a feature similar to NPM distribution tags. +> In those, the version number is the only mechanism to signal pre-releases. To this effect, the version numbers used +> must adhere to the correct local convension (which can be achieved using the existing version suffix features of +> `jsii-pacmak`): +> +> - **NuGet** [honors prerelease identifiers][nuget-versioning] in a way that is compatible with [Semantic Versioning]. +> Using the same version number as the NPM package will result in the correct behavior. The standard behavior of +> `nuget` is to resolve to the _latest stable release_, while resolving to pre-releases requires the user to use a +> pre-release identifier in their dependency specifications. +> - **Maven Central** uses the `-SNAPSHOT` suffix to version numbers to denote versions that are in active development. +> Publishing `SNAPSHOT` involves using a `SNAPSHOT`-specific repository. _Maven Central_ offers a _SNAPSHOT_ +> repository (at `https://oss.sonatype.org/content/repositories/snapshots`), which can be used. In order to install +> `SNAPSHOT` releases, customers must manually enable the `SNAPSHOT` repository in their configuration. +> - **PyPI** uses a specific set of version suffixes to identify pre-releases (`.dev#` for development releases, `.a#` +> for alphas, `.b#` for betas, and `.rc#` for release candidates). Modern package installers ignore pre-releases by +> default. +> +> For **NuGet** and **Maven Central**, the [GitHub Packages] registry could be used as an alternate or additional +> location where customers would consume pre-releases from. + +[semantic versioning]: https://semver.org +[nuget-versioning]: https://docs.microsoft.com/en-us/nuget/concepts/package-versioning#pre-release-versions +[github packages]: https://github.com/features/packages As long as the codebases have not diverged too much, it should be possible to continue forward-porting new developments on top of the `next` branch by simply cherry-picking new commits from the `master` branch. Alternatively, it might be possible to simply periodically merge `master` into `next`. This task can easily be automated. As the codebases grow further appart, manual work may be required in order to forward-port feature work merged in -`master`. As a consequence we will strive to keep divergences to a minimum for as long as possible. Someone, for example -the on-call engineer or a rotating member of the squad in charge of v2 implementation, will be in charge of performing -the manual conflict resolution against automatically filed pull requests as needed. +`master`. As a consequence we will strive to keep divergences to a minimum for as long as possible. The on-call engineer +will be tasked with reviewing and merging automated pull requests created twice a week (e.g: on _Mondays_ and +_Thursdays_), manually resolving merge conflicts as needed. + +## Monolithic Packaging + +The AWS Construct Library will be released as a single artifact, instead of a collection of more than 100 libraries. The +`monocdk-experiment` package has the tools necessary to re-package the existing _hypermodular_ libraries into a single +packaging. Re-using that same process will allow keeping the difference between `master` and `next` as constrained as +possible (reducing the need for manual intervention in forward-porting features). + +No additional work is needed once the `next` branch has been forked from `master`, as the renaming of +`monocdk-experiment` to `aws-cdk-lib` and marking all bundled packages `private` is taken care of at that time. ## Feature Implementation @@ -148,6 +200,11 @@ annotated code, as well as any private function that is no longer used. In the e depend on `@deprecated` code, the implementation in `master` will be fixed to no longer defer into the `@deprecated` feature, and that fix will be forward-ported into the `next` branch in the exact same way that other changes are. +In order to prevent accidental introduction (or re-introduction) of `@deprecated` code in the `next` branch while +forward-porting new developments from `master`, a built-time check will be added that scans the codebase for +`@deprecated` (for example using `grep`), failing the build if occurrences are found. This is not done through +inspection of the _jsii assemblies_ as `@deprecated` code can exist outside of exported API signatures. + ### Resetting v1 feature flags When developing new behaviors that are incompatible with previous ones, feature flags were introduced to allow customers @@ -160,6 +217,15 @@ complicate upgrading applications to the new major version. Feature flags will b where a migration is impossible or difficult, the default state will be changed from disabled to enabled, but users will retain the ability to disable as needed. +> Here is a table summarizing existing feature flags, the migration process, and whether they should be removed or only +> have thier default behavior toggled: +> +> | Feature Flag | Migration | Decision | +> | ----------------------------------------- | ---------------------------------------------------- | --------- | +> | `aws-cdk:enableDiffNoFail` | Adding the `--fail` option reproduces "off" behavior | 🚮 Remove | +> | `@aws-cdk/core:enableStackNameDuplicates` | Update to new file names under `cdk.out` | 🚮 Remove | +> | `@aws-cdk/core:newStyleStackSynthesis` | Re-bootstrap environments | 🚮 Remove | + In order to reduce the codebase divergence between `master` and `next` (in order to minimize the amount of manual work involved in forward-porting features on `next`), existing feature flags must be made version-aware, such that they are enabled by default (and impossible to disable if a clean and reasonably simple migration is possible) when the current @@ -168,20 +234,6 @@ version is greater then `2.0.0-0`. The actual removal of code paths that support the _old behavior_ of feature flags that can no longer be disabled will be deferred to _after_ the new major version has reached _General Availability_. -### Monolithic Packaging - -The AWS Construct Library will be released as a single artifact, instead of a collection of more than 100 libraries. The -`monocdk-experiment` package has the tools necessary to re-package the existing _hypermodular_ libraries into a single -packaging. Re-using that same process will allow keeping the difference between `master` and `next` as constrained as -possible (reducing the need for manual intervention in forward-porting features). - -Consequently, the `monocdk-experiment` package will be renamed so that it is published and advertised as `aws-cdk-lib` -on the `master` branch. Availability of this library as part of CDK v1 is going to provide customers with a stepping -stone to begin migrating their applications to CDK v2. - -Additionally, all modules that are re-packaged as part of `aws-cdk-lib` will be marked as `"private": true` in the -`next` branch, making these available _only_ via `aws-cdk-lib` in CDK v2. - ## Documentation Updates Before formally announcing the availability of CDK v2 for early adopters, a documentation source must be availble to @@ -391,6 +443,7 @@ All users will perform the following to adopt CDK v2 - In Python, manual replacement of import statements migth be necessary - In .NET languages (C#, F#, ...) and Java, the namespace structure from CDK v1 will be retained, removing the need for any code change +1. Adjust code to the removal of the constructs compatibility layer, which is documented in [RFC-192] Users will naturally have to make additional changes when upgrading if they are relying on deprecated APIs or _old behaviors_ from feature flags that are being removed. A [migration guide](#migration-guide) will be written with details @@ -403,3 +456,162 @@ relatively painless for users to adopt. The most prevalent code change required, The challenge for the future is to maintain that experience whenever possible, and wherever it isn't, give users plenty of time and warning to change their code and provide details about a reasonable path to do so without interruptions to their existing cloud resources. + +--- + +# Annexes + +## Annex 1 + +Packages to be included in the monolithic library bundle are the following: + +- All non-deprecated packages whith a name starting with `@aws-cdk/aws-` or `@aws-cdk/alexa-`: + - `@aws-cdk/alexa-ask` + - `@aws-cdk/aws-accessanalyzer` + - `@aws-cdk/aws-acmpca` + - `@aws-cdk/aws-amazonmq` + - `@aws-cdk/aws-amplify` + - `@aws-cdk/aws-apigateway` + - `@aws-cdk/aws-apigatewayv2` + - `@aws-cdk/aws-appconfig` + - `@aws-cdk/aws-applicationautoscaling` + - `@aws-cdk/aws-appmesh` + - `@aws-cdk/aws-appstream` + - `@aws-cdk/aws-appsync` + - `@aws-cdk/aws-athena` + - `@aws-cdk/aws-autoscaling-common` + - `@aws-cdk/aws-autoscaling-hooktargets` + - `@aws-cdk/aws-autoscaling` + - `@aws-cdk/aws-autoscalingplans` + - `@aws-cdk/aws-backup` + - `@aws-cdk/aws-batch` + - `@aws-cdk/aws-budgets` + - `@aws-cdk/aws-cassandra` + - `@aws-cdk/aws-ce` + - `@aws-cdk/aws-certificatemanager` + - `@aws-cdk/aws-chatbot` + - `@aws-cdk/aws-cloud9` + - `@aws-cdk/aws-cloudformation` + - `@aws-cdk/aws-cloudfront` + - `@aws-cdk/aws-cloudtrail` + - `@aws-cdk/aws-cloudwatch-actions` + - `@aws-cdk/aws-cloudwatch` + - `@aws-cdk/aws-codebuild` + - `@aws-cdk/aws-codecommit` + - `@aws-cdk/aws-codedeploy` + - `@aws-cdk/aws-codeguruprofiler` + - `@aws-cdk/aws-codepipeline-actions` + - `@aws-cdk/aws-codepipeline` + - `@aws-cdk/aws-codestar` + - `@aws-cdk/aws-codestarconnections` + - `@aws-cdk/aws-codestarnotifications` + - `@aws-cdk/aws-cognito` + - `@aws-cdk/aws-config` + - `@aws-cdk/aws-datapipeline` + - `@aws-cdk/aws-dax` + - `@aws-cdk/aws-detective` + - `@aws-cdk/aws-directoryservice` + - `@aws-cdk/aws-dlm` + - `@aws-cdk/aws-dms` + - `@aws-cdk/aws-docdb` + - `@aws-cdk/aws-dynamodb` + - `@aws-cdk/aws-ec2` + - `@aws-cdk/aws-ecr-assets` + - `@aws-cdk/aws-ecr` + - `@aws-cdk/aws-ecs-patterns` + - `@aws-cdk/aws-ecs` + - `@aws-cdk/aws-efs` + - `@aws-cdk/aws-eks-legacy` + - `@aws-cdk/aws-eks` + - `@aws-cdk/aws-elasticache` + - `@aws-cdk/aws-elasticbeanstalk` + - `@aws-cdk/aws-elasticloadbalancing` + - `@aws-cdk/aws-elasticloadbalancingv2-actions` + - `@aws-cdk/aws-elasticloadbalancingv2-targets` + - `@aws-cdk/aws-elasticloadbalancingv2` + - `@aws-cdk/aws-elasticsearch` + - `@aws-cdk/aws-emr` + - `@aws-cdk/aws-events-targets` + - `@aws-cdk/aws-events` + - `@aws-cdk/aws-eventschemas` + - `@aws-cdk/aws-fms` + - `@aws-cdk/aws-fsx` + - `@aws-cdk/aws-gamelift` + - `@aws-cdk/aws-globalaccelerator` + - `@aws-cdk/aws-glue` + - `@aws-cdk/aws-greengrass` + - `@aws-cdk/aws-guardduty` + - `@aws-cdk/aws-iam` + - `@aws-cdk/aws-imagebuilder` + - `@aws-cdk/aws-inspector` + - `@aws-cdk/aws-iot` + - `@aws-cdk/aws-iot1click` + - `@aws-cdk/aws-iotanalytics` + - `@aws-cdk/aws-iotevents` + - `@aws-cdk/aws-iotthingsgraph` + - `@aws-cdk/aws-kinesis` + - `@aws-cdk/aws-kinesisanalytics` + - `@aws-cdk/aws-kinesisfirehose` + - `@aws-cdk/aws-kms` + - `@aws-cdk/aws-lakeformation` + - `@aws-cdk/aws-lambda-destinations` + - `@aws-cdk/aws-lambda-event-sources` + - `@aws-cdk/aws-lambda-nodejs` + - `@aws-cdk/aws-lambda` + - `@aws-cdk/aws-logs-destinations` + - `@aws-cdk/aws-logs` + - `@aws-cdk/aws-macie` + - `@aws-cdk/aws-managedblockchain` + - `@aws-cdk/aws-mediaconvert` + - `@aws-cdk/aws-medialive` + - `@aws-cdk/aws-mediastore` + - `@aws-cdk/aws-msk` + - `@aws-cdk/aws-neptune` + - `@aws-cdk/aws-networkmanager` + - `@aws-cdk/aws-opsworks` + - `@aws-cdk/aws-opsworkscm` + - `@aws-cdk/aws-pinpoint` + - `@aws-cdk/aws-pinpointemail` + - `@aws-cdk/aws-qldb` + - `@aws-cdk/aws-ram` + - `@aws-cdk/aws-rds` + - `@aws-cdk/aws-redshift` + - `@aws-cdk/aws-resourcegroups` + - `@aws-cdk/aws-robomaker` + - `@aws-cdk/aws-route53-patterns` + - `@aws-cdk/aws-route53-targets` + - `@aws-cdk/aws-route53` + - `@aws-cdk/aws-route53resolver` + - `@aws-cdk/aws-s3-assets` + - `@aws-cdk/aws-s3-deployment` + - `@aws-cdk/aws-s3-notifications` + - `@aws-cdk/aws-s3` + - `@aws-cdk/aws-sagemaker` + - `@aws-cdk/aws-sam` + - `@aws-cdk/aws-sdb` + - `@aws-cdk/aws-secretsmanager` + - `@aws-cdk/aws-securityhub` + - `@aws-cdk/aws-servicecatalog` + - `@aws-cdk/aws-servicediscovery` + - `@aws-cdk/aws-ses-actions` + - `@aws-cdk/aws-ses` + - `@aws-cdk/aws-sns-subscriptions` + - `@aws-cdk/aws-sns` + - `@aws-cdk/aws-sqs` + - `@aws-cdk/aws-ssm` + - `@aws-cdk/aws-stepfunctions-tasks` + - `@aws-cdk/aws-stepfunctions` + - `@aws-cdk/aws-synthetics` + - `@aws-cdk/aws-transfer` + - `@aws-cdk/aws-waf` + - `@aws-cdk/aws-wafregional` + - `@aws-cdk/aws-wafv2` + - `@aws-cdk/aws-workspaces` +- `@aws-cdk/app-delivery` +- `@aws-cdk/assets` +- `@aws-cdk/cloud-assembly-schema` +- `@aws-cdk/cloudformation-include` +- `@aws-cdk/custom-resource` +- `@aws-cdk/cx-api` +- `@aws-cdk/pipelines` +- `@aws-cdk/region-info` From 7e71ff249a6107087ef9cd9b27883008b88e7e19 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BC=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier-Muller?= <rmuller@amazon.com> Date: Tue, 28 Jul 2020 15:25:43 +0200 Subject: [PATCH 15/21] tighten up v1 deprecation language a bit --- text/0079-cdk-2.0.md | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index 2e8daca2e..63b91250d 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -335,15 +335,22 @@ tooling to remove roadblocks and facilitate migration. ## Deprecation of v1 -Based on the v1 maintenance plan, feature development is to stop on CDK v1, as only bugs reported against CDK v1 are to -be fixed. Back-porting of features is not necessary, although the community is still welcome to back-port features. +Based on the [maintenance policy](#aws-cdk-maintenance-policy), new feature development is to stop on CDK v1, and only +critical bugs and security issues will be addressed in the `v1` release line. -New GitHub labels will be added to differentiate bugs affecting `v1`, `v2` or both. The triaging process will need to be -adjusted to include a determination of whether a bug fix against CDK v1 needs forward-porting to v2 or vice-versa. A -similar provision applies to pull-requests, as only the following should be accepted against v1: +New GitHub labels will be added to differentiate bugs reported against `v1` from those reported against `v2`. Bugs +reported against `v1` will be closed with a standard message during triaging unless they are identified as critical or +security-impacting (meaning they qualify for `P0` handling). -- Features that facilitate migration to v2 -- Features that are back-ported from v2 +A similar provision applies to pull-requests, as they will only be accepted in the `v1` branch if they are non-breaking +and fall into one of the following categories: + +- 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) + +Community pull requests against the `v1` branch may be processed with lower priority than those against `v2`, as the +community is encouraged to shift their efforts towards the latest major version. # AWS CDK Maintenance Policy From 1e5157190f88a2c1e7dd9ecaaeeb748b6160becf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BC=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier-Muller?= <rmuller@amazon.com> Date: Wed, 29 Jul 2020 13:03:43 +0200 Subject: [PATCH 16/21] tweaks --- text/0079-cdk-2.0.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index 63b91250d..fec45d36b 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -238,13 +238,19 @@ deferred to _after_ the new major version has reached _General Availability_. Before formally announcing the availability of CDK v2 for early adopters, a documentation source must be availble to facilitate use of the new repository. The minimum bar should be availability of an API reference documentation for the -v2 codebase that is usable. +v2 codebase that is usable. This entails the following items: + +- Both documentations for `v1` and `v2` must be browseable on the [AWS CDK Reference Documentation] site +- The `v2` documentation site must render the `README.md` document for all _submodules_ together with the API + documentation, with a presentation that is similar to that of `v1` (so migrating users do not have to learn a + completely new reference documentation layout) At the same time, the work to update the [AWS CDK User Guide] should be scoped and planned out. The updates to the User Guide must also include a migration guide to help developers move from CDK v1 over to v2. Special attention will be spent in ensuring the v2 release notes contain a clear and accurate summary of breaking changes and how users should update their applications. +[aws cdk reference documentation]: https://docs.aws.amazon.com/cdk/api/latest/ [aws cdk user guide]: https://docs.aws.amazon.com/cdk/latest/guide/home.html ## Prerelease Announcement @@ -323,7 +329,8 @@ Now that the new major version has been declared _Generally Available_, the prev _maintenance_ mode. Forward porting is no longer exercised: instead, bug fixes on `master` will be back-ported to `v1` when necessary. This means `master` can diverge more significantly from `v1` than in earler stages of the process. -The definition of `v1` feature flags and the code paths supporthing the _old behavior_ of those can be deleted. +The definition of `v1` feature flags and the code paths supporthing the _old behavior_ of those can be deleted (they +were previously simply _neutralized_ in `v2` so that they could no longer be disabled there). ## Monitoring Adoption @@ -470,7 +477,8 @@ their existing cloud resources. ## Annex 1 -Packages to be included in the monolithic library bundle are the following: +Packages that are included in the monolithic library bundle (`monocdk-experiment` to become `aws-cdk-lib`) are the +following: - All non-deprecated packages whith a name starting with `@aws-cdk/aws-` or `@aws-cdk/alexa-`: - `@aws-cdk/alexa-ask` @@ -614,7 +622,6 @@ Packages to be included in the monolithic library bundle are the following: - `@aws-cdk/aws-wafregional` - `@aws-cdk/aws-wafv2` - `@aws-cdk/aws-workspaces` -- `@aws-cdk/app-delivery` - `@aws-cdk/assets` - `@aws-cdk/cloud-assembly-schema` - `@aws-cdk/cloudformation-include` From 2079f0c0bb2fe6ecc1acb409d6dc97fc1f1cf710 Mon Sep 17 00:00:00 2001 From: Romain Marcadier <rmuller@amazon.com> Date: Wed, 29 Jul 2020 14:58:24 +0200 Subject: [PATCH 17/21] Update text/0079-cdk-2.0.md Co-authored-by: Nick Lynch <nlynch@amazon.com> --- text/0079-cdk-2.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index fec45d36b..80722a0b3 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -264,7 +264,7 @@ prerelease announcement should at least mention the following elements: - A provisional list of breaking changes expected to be made to the _AWS Construct Library_ (`aws-cdk-lib`) APIs during the [Construct Library Maintenance Tasks](#construct-library-maintenance-tasks) phase -- A finalized proposal for the CDK [v1 maintenance plan](#ongoing-maintenance-plan), and a call for developers to +- A finalized proposal for the CDK [v1 maintenance plan](#aws-cdk-maintenance-policy), and a call for developers to provide feedback on that - A minimal migration guide for bravehearts who are inclined to try and migrate their existing (**non-production**) applications From 1cbede42a61950b38d27936af3d2b392adbb618c Mon Sep 17 00:00:00 2001 From: Romain Marcadier <rmuller@amazon.com> Date: Wed, 29 Jul 2020 14:58:42 +0200 Subject: [PATCH 18/21] Update text/0079-cdk-2.0.md Co-authored-by: Nick Lynch <nlynch@amazon.com> --- text/0079-cdk-2.0.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index 80722a0b3..626a28c2a 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -508,6 +508,7 @@ following: - `@aws-cdk/aws-cloud9` - `@aws-cdk/aws-cloudformation` - `@aws-cdk/aws-cloudfront` + - `@aws-cdk/aws-cloudfront-origins` - `@aws-cdk/aws-cloudtrail` - `@aws-cdk/aws-cloudwatch-actions` - `@aws-cdk/aws-cloudwatch` From 9bc490516935a9f51b0a4091c47901129df69d42 Mon Sep 17 00:00:00 2001 From: Romain Marcadier <rmuller@amazon.com> Date: Wed, 29 Jul 2020 14:58:55 +0200 Subject: [PATCH 19/21] Update text/0079-cdk-2.0.md Co-authored-by: Nick Lynch <nlynch@amazon.com> --- text/0079-cdk-2.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index 626a28c2a..0353ff7d8 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -14,7 +14,7 @@ to support this strategy. For details on the specific features themselves, refer # Motivation -Since the CDK was announcned as "generally available", the team has tried to limit breaking changes for users. However, +Since the CDK was announced 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 v2 release to signal to users that code changes may be required for adoption. From 2e15f15b384817fa7d3a9b3ec9ebcc31ab3cd02c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BC=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier-Muller?= <rmuller@amazon.com> Date: Mon, 3 Aug 2020 14:57:38 +0200 Subject: [PATCH 20/21] some tweaks and adjustments --- text/0079-cdk-2.0.md | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index 0353ff7d8..54816b90b 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -14,8 +14,8 @@ to support this strategy. For details on the specific features themselves, refer # Motivation -Since the CDK was announced 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 +Since the CDK was announced 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 v2 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 @@ -180,10 +180,20 @@ _Thursdays_), manually resolving merge conflicts as needed. The AWS Construct Library will be released as a single artifact, instead of a collection of more than 100 libraries. The `monocdk-experiment` package has the tools necessary to re-package the existing _hypermodular_ libraries into a single packaging. Re-using that same process will allow keeping the difference between `master` and `next` as constrained as -possible (reducing the need for manual intervention in forward-porting features). - -No additional work is needed once the `next` branch has been forked from `master`, as the renaming of -`monocdk-experiment` to `aws-cdk-lib` and marking all bundled packages `private` is taken care of at that time. +possible (reducing the need for manual intervention in forward-porting features). No additional packaging work is needed +once the `next` branch has been forked from `master`, as the renaming of `monocdk-experiment` to `aws-cdk-lib` and +marking all bundled packages `private` is taken care of at that time. + +However, since users will all use a single `aws-cdk-lib` library, the granularity of information collected via the +`AWS::CDK::Metadata` resource (injected by the [version reporting] feature) will be significantly reduced. In order to +retain ability to provide a signal to customers affected by a security or reliability issue (and not to _all_ customers +using the CDK), the mechanism will need to be updated to enable identifying specific subsets of the construct library. +While the exact design of this change is subject to change, one approach is to generate additional code in the +_CloudFormation Resources_ so they self-report usage, allowing the `AWS::CDK::Metadata` to include data as specific as +the resource types being used when synthesizing a stack. The collected data will remain completely transparent and +auditable by users, who will naturally retain the ability to opt out of this feature. + +[version reporting]: https://docs.aws.amazon.com/cdk/latest/guide/cli.html#version_reporting ## Feature Implementation From 7f2799c813cec278793719f86af37cfe7224e43d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9F=91=A8=F0=9F=8F=BC=E2=80=8D=F0=9F=92=BB=20Romain=20M?= =?UTF-8?q?arcadier-Muller?= <rmuller@amazon.com> Date: Wed, 12 Aug 2020 10:53:19 +0200 Subject: [PATCH 21/21] final changes --- text/0079-cdk-2.0.md | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index 54816b90b..a60decef3 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -126,7 +126,8 @@ v1 will be front-loaded. This includes all work that can be prepared without bre removal of deprecated memebers would thus leave only the new API in v2) - Work identified in [RFC-192] to be done directly in v1, ahead of the actual removal of the _constructs compatibility layer_ in v2 -- Making the default state of _feature flags_ version-aware + - [Project board](https://github.com/aws/aws-cdk/projects/9) +- Making the default state of _feature flags_ version-aware (i.e: the default is "off" in `v1`, and "on" in `v2`) ## Forking v2 out of v1 @@ -170,6 +171,10 @@ As long as the codebases have not diverged too much, it should be possible to co on top of the `next` branch by simply cherry-picking new commits from the `master` branch. Alternatively, it might be possible to simply periodically merge `master` into `next`. This task can easily be automated. +A new standard operating procedure (SOP / MCM) will be made to support manually releasing a CDK `v2` release until this +process is fully automated. Additionally, canaries and integration tests need to be prepared to ensure the ongoing +quality of the `v2` release stream. + As the codebases grow further appart, manual work may be required in order to forward-port feature work merged in `master`. As a consequence we will strive to keep divergences to a minimum for as long as possible. The on-call engineer will be tasked with reviewing and merging automated pull requests created twice a week (e.g: on _Mondays_ and @@ -246,7 +251,7 @@ deferred to _after_ the new major version has reached _General Availability_. ## Documentation Updates -Before formally announcing the availability of CDK v2 for early adopters, a documentation source must be availble to +Before formally announcing the availability of CDK v2 for early adopters, a documentation source must be availbable to facilitate use of the new repository. The minimum bar should be availability of an API reference documentation for the v2 codebase that is usable. This entails the following items: @@ -363,6 +368,7 @@ A similar provision applies to pull-requests, as they will only be accepted in t and fall into one of the following categories: - features dedicated to facilitating migration from `v1` to `v2` + - e.g: outputting synth-time warnings when @deprecated APIs are used to facilitate discovery - features back-ported from `v2` - bug fixes (where relevant, the author is expected to submit the `v2` fix at the same time) @@ -481,6 +487,23 @@ The challenge for the future is to maintain that experience whenever possible, a of time and warning to change their code and provide details about a reasonable path to do so without interruptions to their existing cloud resources. +# Execution Plan + +See GitHub Project Board: [aws/aws-cdk@10](https://github.com/aws/aws-cdk/projects/10) + +Changes needed in auxiliary projects: + +- **jsii** - Improved prerelease support in _jsii_ (and jsii-pacmak) + - Allowing per-language tuning of prerelease versions (Python uses some suffixes, Java uses -SNAPSHOT, NuGet & NPM use + semver prerelease labels) +- **jsii** - Support for submodule-level README.md for the documentation site +- **jsii** - Support for multiple versions on a single docsite +- **DelivLib** - Support for prerelease publishing + - Publish NPM packages to a different dist-tag than latest + - Publish Java to SNAPSHOT repositories instead of the regular repository +- **DelivLib** - Support for automated forward-porting +- **DelivLib** - Automated daily releases + --- # Annexes