rfc 79: cdk v2.0 - deprecated APIs (#235)

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