From c29f01906d48fcb6d2e4ab777f0e4ef344bf95c5 Mon Sep 17 00:00:00 2001 From: Niranjan Jayakar Date: Mon, 24 Aug 2020 15:58:39 +0100 Subject: [PATCH] rfc 79: cdk v2.0 - deprecated APIs --- text/0079-cdk-2.0.md | 69 ++++++++++++++++++++++++++++++++------------ 1 file changed, 50 insertions(+), 19 deletions(-) diff --git a/text/0079-cdk-2.0.md b/text/0079-cdk-2.0.md index a60decef3..eaff195f0 100644 --- a/text/0079-cdk-2.0.md +++ b/text/0079-cdk-2.0.md @@ -131,7 +131,7 @@ v1 will be front-loaded. This includes all work that can be prepared without bre ## 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, where the +The forking point will be achieved by cutting a new `v2` 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 @@ -168,8 +168,8 @@ validated. Releases will be automatically published, however using the `next` NP [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. +on top of the `v2` branch by simply cherry-picking new commits from the `master` branch. Alternatively, it might be +possible to simply periodically merge `master` into `v2`. 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 @@ -184,9 +184,9 @@ _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 +packaging. Re-using that same process will allow keeping the difference between `master` and `v2` as constrained as 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 +once the `v2` 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 @@ -210,15 +210,23 @@ The definition of `@deprecated` in the CDK specifies that annotated APIs will be release. Consequently, we will systematically remove all `@deprecated` APIs from the codebase upon cutting a new major version. -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. +Tooling will enforce that no deprecated APIs methods, properties, interfaces or classes will be used within the CDK +repository. This also applies to tests, with an option for individual overrides, in the case of testing the deprecated +APIs themselves. -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. +The `jsii` binary will accept a `--no-deprecated` flag that will skip deprecated APIs from the `.jsii` binary. In +conjunction, deprecated APIs will be stripped off the typescript files as part of producing the monolithic package, +`aws-cdk-lib`, similar to [import rewrites]. + +When CDK v2.0 become generally available, the source code will be updated to remove all use of `@deprecated`. +This will occur as part of flipping `master` to point to the `v2` branch, with a code freeze of at most 2 days +instituted. +Additionally, the `--no-deprecated` flag and the typescript transform will be dropped, now enabling API deprecations on +CDKv2. + +**Why not remove these by hand?** See [alternatives section](#removal-of-deprecated-apis---why-not-remove-these-by-hand). + +[import rewrites]: https://github.com/aws/aws-cdk/tree/master/packages/%40monocdk-experiment/rewrite-imports ### Resetting v1 feature flags @@ -241,8 +249,8 @@ retain the ability to disable as needed. > | `@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 +In order to reduce the codebase divergence between `master` and `v2` (in order to minimize the amount of manual work +involved in forward-porting features on `v2`), 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 version is greater then `2.0.0-0`. @@ -288,7 +296,7 @@ prerelease announcement should at least mention the following elements: 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 +party contributors) will be allowed to introduce API-breaking changes in the `v2` 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 @@ -332,9 +340,9 @@ Once the criteria have been satisfied, the high-level procedure for officially r 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. Make `v2` the new `master` branch: + 1. Force-push `v2` on `master` + 1. Delete `v2` 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 @@ -461,6 +469,29 @@ 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. +## Removal of @deprecated APIs - Why not remove these by hand? + +An alternative that was considered is to remove these by hand in the `v2` branch. As of Aug 24, 2020, there are ~250 +deprecated properties, methods and classes combined, distributed across ~80 files. + +While most of these would be properties and simple public APIs being deprecated, they also include larger sections +such as entire classes. The main challenge with this approach are the merge conflicts that will arise when merging +changes from the `master` branch onto the `v2` branch. + +Simple changes to files that contain a few deprecated APIs will pose no difficulty in `git` resolving these conflicts. +However, any changes to the implementation of a deprecated API, file refactor or any other major changes will require +non-trivial human intervention. It is unclear who owns the resolution of these conflicts, at what point they will be +resolved (i.e., during PR, during forward merge, during pipeline approval). + +We expect the forked state of the system (i.e., two active branches) to exist for several months as we work through the +changes to have 'CDK 2.0' generally available. As we get closer to 'CDK v2.0', we must expect the list of major changes +to this major release to expand. This may manifest as major or significant changes to the code and its structure. +We must also expect an increased rate of deprecated APIs across the CDK as the reality of CDKv2 gets closer, with the +team looking to use this opportunity to implement major changes. + +The continuous overhead of conflict resolution or a ban on large refactors or changes is an unreasonable expectation on +the team for such an extended period of time. + # Adoption Strategy All users will perform the following to adopt CDK v2