Skip to content

Commit a5ff631

Browse files
authored
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*
1 parent 9d1b2c7 commit a5ff631

File tree

1 file changed

+3
-21
lines changed

1 file changed

+3
-21
lines changed

CONTRIBUTING.md

+3-21
Original file line numberDiff line numberDiff line change
@@ -803,35 +803,17 @@ The pattern is simple:
803803
with the name of the context key that **enables** this new feature (for
804804
example, `ENABLE_STACK_NAME_DUPLICATES`). The context key should be in the
805805
form `module.Type:feature` (e.g. `@aws-cdk/core:enableStackNameDuplicates`).
806-
2. Use `node.tryGetContext(cxapi.ENABLE_XXX)` to check if this feature is enabled
806+
2. Use `FeatureFlags.of(construct).isEnabled(cxapi.ENABLE_XXX)` to check if this feature is enabled
807807
in your code. If it is not defined, revert to the legacy behavior.
808808
3. Add your feature flag to the `FUTURE_FLAGS` map in
809809
[cx-api/lib/features.ts](https://github.com/aws/aws-cdk/blob/master/packages/%40aws-cdk/cx-api/lib/features.ts).
810810
This map is inserted to generated `cdk.json` files for new projects created
811811
through `cdk init`.
812-
4. In your PR title (which goes into CHANGELOG), add a `(under feature flag)` suffix. e.g:
812+
4. In your tests, use the `testFutureBehavior` and `testLegacyBehavior` [jest helper methods] to test the enabled and disabled behavior.
813+
5. In your PR title (which goes into CHANGELOG), add a `(under feature flag)` suffix. e.g:
813814

814815
`fix(core): impossible to use the same physical stack name for two stacks (under feature flag)`
815816

816-
In the [next major version of the
817-
CDK](https://github.com/aws/aws-cdk/issues/3398) we will either remove the
818-
legacy behavior or flip the logic for all these features and then
819-
reset the `FEATURE_FLAGS` map for the next cycle.
820-
821-
### Feature Flags - CDKv2
822-
823-
We have started working on the next version of the CDK, specifically CDKv2. This is currently being maintained
824-
on a separate branch `v2-main` whereas `master` continues to track versions `1.x`.
825-
826-
Feature flags introduced in the CDK 1.x and removed in 2.x, must be added to the `FUTURE_FLAGS_EXPIRED` list in
827-
[cx-api/lib/features.ts](https://github.com/aws/aws-cdk/blob/master/packages/%40aws-cdk/cx-api/lib/features.ts)
828-
on the `v2-main` branch.
829-
This will make the default behaviour in CDKv2 as if the flag is enabled and also prevents users from disabling
830-
the feature flag.
831-
832-
A couple of [jest helper methods] are available for use with unit tests. These help run unit tests that test
833-
behaviour when flags are enabled or disabled in the two major versions.
834-
835817
[jest helper methods]: https://github.com/aws/aws-cdk/blob/master/tools/@aws-cdk/cdk-build-tools/lib/feature-flag.ts
836818

837819
## Versioning and Release

0 commit comments

Comments
 (0)