RFC 249: V2 Experiments (#250)

Initial version of the "Experiments" RFC. Still requires further iterations, add adding more options. Pushing it to make collaboration on it easier.
aws · Oct 14, 2020 · da154da · da154da
1 parent 416b074
commit da154da
Show file tree

Hide file tree

Showing 7 changed files with 953 additions and 399 deletions.
diff --git a/0000-template.md b/0000-template.md
@@ -117,7 +117,7 @@ tracking issue: https://github.com/aws/aws-cdk-rfcs/issues/yyy
 > the RFC is approved, create GitHub issues for these issues and update this RFC
 > of the project board with these issue IDs.
 
-## Appendix: ....
+## Appendix
 
 Feel free to add any number of appendices as you see fit. Appendices are
 expected to allow readers to dive deeper to certain sections if they like. For

diff --git a/text/00110-cli-framework-compatibility-strategy.md b/text/00110-cli-framework-compatibility-strategy.md
@@ -5,8 +5,6 @@ rfc pr: https://github.com/aws/aws-cdk-rfcs/pull/111
 related issue: https://github.com/aws/aws-cdk-rfcs/issues/110
 ---
 
-<!-- replace the blockquoted sections with your content -->
-
 # Summary
 
 This RFC addresses compatibility concerns for developing different parts of the
@@ -33,14 +31,14 @@ either of the two CDK components:
 - CLI upgrades are compatible. New CLI versions should work with older framework
   versions, and all existing functionality is preserved.
 
-  > By _functionality_, we mean that the CLI is able to properly interpret older
-  > frameworks and perform the necessary actions to support the existing
-  > behavior.
+> By _functionality_, we mean that the CLI is able to properly interpret older
+> frameworks and perform the necessary actions to support the existing behavior.
 
 - Framework upgrades are comptabile **unless** the _cloud-assembly-schema_ has
   changed, in which case, we will require the user to upgrade the CLI as well.
 
-      > We will treat every change to the schema as a "breaking" one, [details](#schema-changes) below.
+> We will treat every change to the schema as a "breaking" one,
+> [details](#schema-changes) below.
 
 # Motivation
 
@@ -90,7 +88,7 @@ const toolkitVersion = parseSemver(CLOUD_ASSEMBLY_VERSION);
 The CLI version takes the value of the latest cx-protocol version, and not the
 actual CLI version.
 
-```typescript
+```ts
 // if framework > cli, we require a newer cli version
 if (semver.gt(frameworkVersion, toolkitVersion)) {
   throw new Error(
@@ -225,7 +223,7 @@ leverage `jsii` to accomplish this. For example, this is an excerpt from the
 This means that, if we remove the `path` property from
 `ContainerImageAssetMetadataEntry`, jsii should produce an error, and indeed:
 
-```console
+```sh
 ❯ yarn compat
 PROP @aws-cdk/cx-api.ContainerImageAssetMetadataEntry.path: has been removed [removed:@aws-cdk/cx-api.ContainerImageAssetMetadataEntry.path]
 ```
@@ -342,7 +340,7 @@ de-serialize the `Cloud-Assembly`:
 
 in `exec.ts`
 
-```typescript
+```ts
 var assembly;
 
 if ((await fs.pathExists(app)) && (await fs.stat(app)).isDirectory()) {
@@ -436,7 +434,7 @@ As already mentioned, _cloud-assembly-schema_ API breakage is not the only thing
 that can go wrong. This is to ensure that we don't introduce breaking changes to
 the CLI itself. The plan here is fairly straight forward:
 
-```console
+```sh
 git checkout v${LATEST_PUBLISHED_VERSION}
 npm install /path/to/aws-cdk
 npm install /path/to/packages/*

diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md
@@ -115,20 +115,38 @@ is 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. [Monolithic Packaging](#monolithic-packaging)
-1. [Package Managers](#releasing-to-package-managers)
-1. [Make the necessary code changes to implement all features scoped in for v2](#feature-implementation)
-1. [Prepare documentation updates](#documentation-updates)
-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)
-1. [Announce General Availability](#general-availability)
-1. [Clean up dead code](#clean-up)
-1. [Monitor adoption of the new version](#monitoring-adoption)
-1. [Deprecation of v1](#deprecation-of-v1)
+- [Summary](#summary)
+- [Motivation](#motivation)
+- [Scope](#scope)
+  - [Changes considered for v2 inclusion](#changes-considered-for-v2-inclusion)
+- [Detailed Design](#detailed-design)
+  - [Overview](#overview)
+  - [Preliminary work in v1](#preliminary-work-in-v1)
+  - [Forking v2 out of v1](#forking-v2-out-of-v1)
+  - [Monolithic Packaging](#monolithic-packaging)
+  - [Releasing to Package Managers](#releasing-to-package-managers)
+  - [Feature Implementation](#feature-implementation)
+    - [Removal of `@deprecated` APIs](#removal-of-deprecated-apis)
+    - [Resetting v1 feature flags](#resetting-v1-feature-flags)
+  - [Documentation Updates](#documentation-updates)
+  - [Prerelease Announcement](#prerelease-announcement)
+  - [Construct Library Maintenance Tasks](#construct-library-maintenance-tasks)
+  - [Developer Preview](#developer-preview)
+  - [Feedback Phase](#feedback-phase)
+  - [General Availability](#general-availability)
+  - [Clean Up](#clean-up)
+  - [Monitoring Adoption](#monitoring-adoption)
+  - [Deprecation of v1](#deprecation-of-v1)
+- [AWS CDK Maintenance Policy](#aws-cdk-maintenance-policy)
+- [Rationale and Alternatives](#rationale-and-alternatives)
+  - [Rationale](#rationale)
+  - [Alternatives](#alternatives)
+  - [Removal of @deprecated APIs - Why not remove these by hand?](#removal-of-deprecated-apis---why-not-remove-these-by-hand)
+- [Adoption Strategy](#adoption-strategy)
+- [Future Possibilities](#future-possibilities)
+- [Execution Plan](#execution-plan)
+- [Annexes](#annexes)
+  - [Annex 1](#annex-1)
 
 ## Preliminary work in v1
 
@@ -193,7 +211,6 @@ published, however using the `next` NPM distribution tag instead of `latest`.
   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 `v2` branch by simply
 cherry-picking new commits from the `master` branch. Alternatively, it might be
@@ -242,36 +259,44 @@ will naturally retain the ability to opt out of this feature.
 
 ## Releasing to Package Managers
 
-`aws-cdk-lib` will be released to the various package managers under the following package name.
+`aws-cdk-lib` will be released to the various package managers under the
+following package name.
 
-| Github & NPM  |         Maven Central        |      PyPI     |       NuGet      |
+| Github & NPM  | Maven Central                | PyPI          | NuGet            |
 | ------------- | ---------------------------- | ------------- | ---------------- |
 | `aws-cdk-lib` | `software.amazon.awscdk.lib` | `aws-cdk-lib` | `Amazon.CDK.Lib` |
 
-CDKv2 will be published in three phases - **alpha**, **release candidate** and finally **generally available**.
-During the first two phases, packages will be published with the base version of `2.0.0` and every release will use a
-sequentially increasing pre-release identifier.
-The following table describes the versioning scheme in the different package managers across the different phases.
-
-|                  |              Github & NPM             |             Maven Central             |             PyPI              |                NuGet                  |
-| ---------------- | ------------------------------------- | ------------------------------------- | ----------------------------- | ------------------------------------- |
-|    **Spec**      |         [semantic versioning]         |          [pom version order]          |     [python packaging]        |           [nuget versioning]          |
-|    **Alpha**     | `2.0.0-alpha.1` <br/> `2.0.0-alpha.2` | `2.0.0-alpha.1` <br/> `2.0.0-alpha.2` |  `2.0.0.a1` <br/> `2.0.0.a2`  | `2.0.0-alpha.1` <br/> `2.0.0-alpha.2` |
-|  **DevPreview**  |    `2.0.0-rc.1` <br/> `2.0.0-rc.2`    |    `2.0.0-rc.1` <br/> `2.0.0-rc.2`    | `2.0.0.rc1` <br/> `2.0.0.rc2` |    `2.0.0-rc.1` <br/> `2.0.0-rc.2`    |
-|      **GA**      |         `2.0.0` <br/> `2.1.0`         |         `2.0.0` <br/> `2.1.0`         |     `2.0.0` <br/> `2.1.0`     |         `2.0.0` <br/> `2.1.0`         |
-
-Besides the pre-releases suffix, NPM releases during the alpha and developer preview phases will also include a `v2`
-distribution tag. During these two phases, the `latest` distribution tag will continue to track the latest version of
-CDKv1, i.e., `1.x.y`.
-
-When CDKv2 is declared GA, the `v2` distribution tag will be updated once to match the first GA release, and the
-`latest` distribution tag will start tracking the versions of CDKv2. A new distribution tag called `v1` will be
+CDKv2 will be published in three phases - **alpha**, **release candidate** and
+finally **generally available**. During the first two phases, packages will be
+published with the base version of `2.0.0` and every release will use a
+sequentially increasing pre-release identifier. The following table describes
+the versioning scheme in the different package managers across the different
+phases.
+
+|                | Github & NPM                          | Maven Central                         | PyPI                          | NuGet                                 |
+| -------------- | ------------------------------------- | ------------------------------------- | ----------------------------- | ------------------------------------- |
+| **Spec**       | [semantic versioning]                 | [pom version order]                   | [python packaging]            | [nuget versioning]                    |
+| **Alpha**      | `2.0.0-alpha.1` <br/> `2.0.0-alpha.2` | `2.0.0-alpha.1` <br/> `2.0.0-alpha.2` | `2.0.0.a1` <br/> `2.0.0.a2`   | `2.0.0-alpha.1` <br/> `2.0.0-alpha.2` |
+| **DevPreview** | `2.0.0-rc.1` <br/> `2.0.0-rc.2`       | `2.0.0-rc.1` <br/> `2.0.0-rc.2`       | `2.0.0.rc1` <br/> `2.0.0.rc2` | `2.0.0-rc.1` <br/> `2.0.0-rc.2`       |
+| **GA**         | `2.0.0` <br/> `2.1.0`                 | `2.0.0` <br/> `2.1.0`                 | `2.0.0` <br/> `2.1.0`         | `2.0.0` <br/> `2.1.0`                 |
+
+Besides the pre-releases suffix, NPM releases during the alpha and developer
+preview phases will also include a `v2` distribution tag. During these two
+phases, the `latest` distribution tag will continue to track the latest version
+of CDKv1, i.e., `1.x.y`.
+
+When CDKv2 is declared GA, the `v2` distribution tag will be updated once to
+match the first GA release, and the `latest` distribution tag will start
+tracking the versions of CDKv2. A new distribution tag called `v1` will be
 created to track the latest release of CDK `1.x.y`.
 
 [semantic versioning]: https://semver.org/#spec-item-9
-[pom version order]: https://maven.apache.org/pom.html#Version_Order_Specification
-[nuget versioning]: https://docs.microsoft.com/en-us/nuget/concepts/package-versioning#pre-release-versions
-[python packaging]: https://packaging.python.org/guides/distributing-packages-using-setuptools/#pre-release-versioning
+[pom version order]:
+  https://maven.apache.org/pom.html#Version_Order_Specification
+[nuget versioning]:
+  https://docs.microsoft.com/en-us/nuget/concepts/package-versioning#pre-release-versions
+[python packaging]:
+  https://packaging.python.org/guides/distributing-packages-using-setuptools/#pre-release-versioning
 
 ## Feature Implementation