feat(cx-api): clean up features.ts

Clean up features.ts such that it will include only things related to feature flags in order to make it easier for users to discover and add feature flags in one place. Merged it with the contents of `future.ts` and updates contribution guide to that end.

The other context keys that were in `feature.ts` were not actually feature flags but rather application switches, so these were moved to `app.ts`.

Fixes #6098

CONTRIBUTING.md

@@ -635,8 +635,8 @@ The pattern is simple:
    form `module.Type:feature` (e.g. `@aws-cdk/core:enableStackNameDuplicates`).
 2. Use `node.tryGetContext(cxapi.ENABLE_XXX)` to check if this feature is enabled
    in your code. If it is not defined, revert to the legacy behavior.
-3. Add your feature flag to
-   [cx-api/lib/future.ts](https://github.com/aws/aws-cdk/blob/master/packages/%40aws-cdk/cx-api/lib/future.ts).
+3. Add your feature flag to the `FUTURE_FLAGS` map in
+   [cx-api/lib/features.ts](https://github.com/aws/aws-cdk/blob/master/packages/%40aws-cdk/cx-api/lib/features.ts).
    This map is inserted to generated `cdk.json` files for new projects created
    through `cdk init`.
 4. In your PR title (which goes into CHANGELOG), add a `(under feature flag)` suffix. e.g:

packages/@aws-cdk/cx-api/lib/app.ts

@@ -0,0 +1,29 @@
+// --------------------------------------------------------------------------------
+// This file declares context keys that are used by the CLI to control the
+// behavior of CDK apps. Contrary to feature flags (which are defined under
+// `features.ts`) these options are not bound to be removed in the next major
+// version.
+// --------------------------------------------------------------------------------
+
+/**
+ * Enables the embedding of the "aws:cdk:path" in CloudFormation template metadata.
+ */
+export const PATH_METADATA_ENABLE_CONTEXT = 'aws:cdk:enable-path-metadata';
+
+/**
+ * Disable the collection and reporting of version information.
+ */
+export const DISABLE_VERSION_REPORTING = 'aws:cdk:disable-version-reporting';
+
+/**
+ * If this is set, asset staging is disabled. This means that assets will not be copied to
+ * the output directory and will be referenced with absolute source paths.
+ */
+export const DISABLE_ASSET_STAGING_CONTEXT = 'aws:cdk:disable-asset-staging';
+
+/**
+ * If this context key is set, the CDK will stage assets under the specified
+ * directory. Otherwise, assets will not be staged.
+ * Omits stack traces from construct metadata entries.
+ */
+export const DISABLE_METADATA_STACK_TRACE = 'aws:cdk:disable-stack-trace';

packages/@aws-cdk/cx-api/lib/features.ts

@@ -1,26 +1,12 @@
-
-/**
- * Enables the embedding of the "aws:cdk:path" in CloudFormation template metadata.
- */
-export const PATH_METADATA_ENABLE_CONTEXT = 'aws:cdk:enable-path-metadata';
-
-/**
- * Disable the collection and reporting of version information.
- */
-export const DISABLE_VERSION_REPORTING = 'aws:cdk:disable-version-reporting';
-
-/**
- * If this is set, asset staging is disabled. This means that assets will not be copied to
- * the output directory and will be referenced with absolute source paths.
- */
-export const DISABLE_ASSET_STAGING_CONTEXT = 'aws:cdk:disable-asset-staging';
-
-/**
- * If this context key is set, the CDK will stage assets under the specified
- * directory. Otherwise, assets will not be staged.
- * Omits stack traces from construct metadata entries.
- */
-export const DISABLE_METADATA_STACK_TRACE = 'aws:cdk:disable-stack-trace';
+// --------------------------------------------------------------------------------
+// This file defines context keys that enable certain features that are
+// implemented behind a flag in order to preserve backwards compatibility for
+// existing apps. When a new app is initialized through `cdk init`, the CLI will
+// automatically add enable these features by adding them to the generated
+// `cdk.json` file. In the next major release of the CDK, these feature flags
+// will be removed and will become the default behavior.
+// See https://github.com/aws/aws-cdk-rfcs/blob/master/text/0055-feature-flags.md
+// --------------------------------------------------------------------------------
 
 /**
  * If this is set, multiple stacks can use the same stack name (e.g. deployed to
@@ -39,4 +25,24 @@ export const ENABLE_STACK_NAME_DUPLICATES_CONTEXT = '@aws-cdk/core:enableStackNa
  *
  * Use `cdk diff --fail` to exit with 1 if there's a diff.
  */
-export const ENABLE_DIFF_NO_FAIL = 'aws-cdk:enableDiffNoFail';
+export const ENABLE_DIFF_NO_FAIL_CONTEXT = 'aws-cdk:enableDiffNoFail';
+/** @deprecated use `ENABLE_DIFF_NO_FAIL_CONTEXT` */
+export const ENABLE_DIFF_NO_FAIL = ENABLE_DIFF_NO_FAIL_CONTEXT;
+
+/**
+ * This map includes context keys and values for feature flags that enable
+ * capabilities "from the future", which we could not introduce as the default
+ * behavior due to backwards compatibility for existing projects.
+ *
+ * New projects generated through `cdk init` will include these flags in their
+ * generated `cdk.json` file.
+ *
+ * When we release the next major version of the CDK, we will flip the logic of
+ * these features and clean up the `cdk.json` generated by `cdk init`.
+ *
+ * Tests must cover the default (disabled) case and the future (enabled) case.
+ */
+export const FUTURE_FLAGS = {
+  [ENABLE_STACK_NAME_DUPLICATES_CONTEXT]: 'true',
+  [ENABLE_DIFF_NO_FAIL_CONTEXT]: 'true',
+};

packages/@aws-cdk/cx-api/lib/index.ts

@@ -12,6 +12,6 @@ export * from './assets';
 export * from './environment';
 export * from './metadata';
 export * from './features';
-export * from './future';
+export * from './app';
 
 export { CLOUD_ASSEMBLY_VERSION } from './versioning';