diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6a552e1c9af3f..662cfae0db1d0 100644 --- a/CONTRIBUTING.md +++ b/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: diff --git a/packages/@aws-cdk/cx-api/lib/app.ts b/packages/@aws-cdk/cx-api/lib/app.ts new file mode 100644 index 0000000000000..d135e9cf40f07 --- /dev/null +++ b/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'; diff --git a/packages/@aws-cdk/cx-api/lib/features.ts b/packages/@aws-cdk/cx-api/lib/features.ts index 83beca62d90b2..ca146e6d54522 100644 --- a/packages/@aws-cdk/cx-api/lib/features.ts +++ b/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', +}; diff --git a/packages/@aws-cdk/cx-api/lib/future.ts b/packages/@aws-cdk/cx-api/lib/future.ts deleted file mode 100644 index 143a6624c8575..0000000000000 --- a/packages/@aws-cdk/cx-api/lib/future.ts +++ /dev/null @@ -1,19 +0,0 @@ -import { ENABLE_DIFF_NO_FAIL, ENABLE_STACK_NAME_DUPLICATES_CONTEXT } from "./features"; - -/** - * 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]: 'true', -}; diff --git a/packages/@aws-cdk/cx-api/lib/index.ts b/packages/@aws-cdk/cx-api/lib/index.ts index 26c5098614da6..afcc102b8f8ac 100644 --- a/packages/@aws-cdk/cx-api/lib/index.ts +++ b/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';