From a5ff6314c07cc7ae295f447e2679b838b81a01cf Mon Sep 17 00:00:00 2001 From: Nick Lynch Date: Wed, 19 Jan 2022 19:31:46 +0000 Subject: [PATCH] chore(docs): improve and clean up CONTRIBUTING for feature flags (#18485) Make both sets of helper methods (`FeatureFlags.of(..).isEnabled` and `testFutureBehavior`/`testLegacyBehavior`) more prominent, and clean up the language around v2 and flipping behavior there, as that's no longer relevant. ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license* --- CONTRIBUTING.md | 24 +++--------------------- 1 file changed, 3 insertions(+), 21 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a16033a986b29..36045a4661c51 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -803,35 +803,17 @@ The pattern is simple: with the name of the context key that **enables** this new feature (for example, `ENABLE_STACK_NAME_DUPLICATES`). The context key should be in the form `module.Type:feature` (e.g. `@aws-cdk/core:enableStackNameDuplicates`). -2. Use `node.tryGetContext(cxapi.ENABLE_XXX)` to check if this feature is enabled +2. Use `FeatureFlags.of(construct).isEnabled(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 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: +4. In your tests, use the `testFutureBehavior` and `testLegacyBehavior` [jest helper methods] to test the enabled and disabled behavior. +5. In your PR title (which goes into CHANGELOG), add a `(under feature flag)` suffix. e.g: `fix(core): impossible to use the same physical stack name for two stacks (under feature flag)` -In the [next major version of the -CDK](https://github.com/aws/aws-cdk/issues/3398) we will either remove the -legacy behavior or flip the logic for all these features and then -reset the `FEATURE_FLAGS` map for the next cycle. - -### Feature Flags - CDKv2 - -We have started working on the next version of the CDK, specifically CDKv2. This is currently being maintained -on a separate branch `v2-main` whereas `master` continues to track versions `1.x`. - -Feature flags introduced in the CDK 1.x and removed in 2.x, must be added to the `FUTURE_FLAGS_EXPIRED` list in -[cx-api/lib/features.ts](https://github.com/aws/aws-cdk/blob/master/packages/%40aws-cdk/cx-api/lib/features.ts) -on the `v2-main` branch. -This will make the default behaviour in CDKv2 as if the flag is enabled and also prevents users from disabling -the feature flag. - -A couple of [jest helper methods] are available for use with unit tests. These help run unit tests that test -behaviour when flags are enabled or disabled in the two major versions. - [jest helper methods]: https://github.com/aws/aws-cdk/blob/master/tools/@aws-cdk/cdk-build-tools/lib/feature-flag.ts ## Versioning and Release