rfc: feature flags #4925
rfc: feature flags #4925
Conversation
Design proposal for a pattern/mechanism that will allow us to introduce breaking capabilities which will only be applied to new projects created by "cdk init" and won't break old projects without explicit action from the user.
|
Thanks so much for taking the time to contribute to the AWS CDK ❤️ We will shortly assign someone to review this pull request and help get it
|
|
|
||
| We considered an alternative of "bundling" new capabilities under a single flag | ||
| that specifies the CDK version which created the project, but this means that | ||
| users won't have the ability to pick and choose which future capabilities they |
There was a problem hiding this comment.
Not exactly true, the 2 alternatives could be combined, as I described on the other PR.
There was a problem hiding this comment.
I know, but it feels like over-designing this without having sufficient evidence that it's required. This is not a one-way-door. We can always add "feature groups" later which will enable a whole bunch of feature flags with a single switch (and it could be a version number if we decide it's useful).
Let's start with the basic granular and simple mechanism and then evolve it as need arises, ok?
There was a problem hiding this comment.
Added a new under a new section for "future development"
design/feature-flags.md
Outdated
| default (so existing projects will not be affected) but enabled automatically | ||
| for new projects created through `cdk init`. | ||
|
|
||
| > The name "**future flags**" is a wordplay on "feature flags" (dah!) to |
There was a problem hiding this comment.
I don't think people won't have to deal with this enough that the wordplay is worth it. To my mind, it's only confusing. But I don't feel strongly about it either way.
There was a problem hiding this comment.
ok, changed to "feature flags".
There was a problem hiding this comment.
Thanks for clipping my wings JK
AWS CodeBuild CI Report
Powered by github-codebuild-logs, available on the AWS Serverless Application Repository |
AWS CodeBuild CI Report
Powered by github-codebuild-logs, available on the AWS Serverless Application Repository |
and add a few ideas from the PR
AWS CodeBuild CI Report
Powered by github-codebuild-logs, available on the AWS Serverless Application Repository |
AWS CodeBuild CI Report
Powered by github-codebuild-logs, available on the AWS Serverless Application Repository |
There was a problem hiding this comment.
I still don't like the aesthetics of the proposed solution, and I think it's wrong to burden all future projects with backwards compatibility cruft (even if it's only 1 or 2 flags). Also not looking forward to fielding all the "what is this flag in my configuration doing?" customer questions, given that the answer will be some form of "just leave it there, it's not really intended to be changed(*)"
However, I know you're antsing to get this out and I don't want to hold up progress, so I will approve.
(*) And yes, I know that technically users have the opportunity to change it if they want to, but they're really not supposed to. The NEW behavior is the one we want to encourage and we only do it by flag because we're scared of breaking current users. So effectively we're stuffing 99% of user's configs full of flags they can look at but shouldn't really be touching.
AWS CodeBuild CI Report
Powered by github-codebuild-logs, available on the AWS Serverless Application Repository |
|
@rix0rrr as I said, I am not against introducing a version-based or group-based mechanism on top of this. There is no contradiction. Let's see how this behaves and iterate. |
…feature flag) Since we used the stack name as the template file name, if users wanted to use the same stack name in two environments, the emitted templates overwrote each other. Furthermore, the CLI used the artifact ID as the stack name, so this became a bit more complex. This means that `assembly.getStack()` is now ambiguous, so I renamed it `getStackByName` which fails if there are two stacks with the same name (legitimate) and added `getStackArtifact` which uses the artifact ID. The core library will effectively generate identical cloud assemblies if the stack name and artifact IDs are the same, and to ensure backwards compat, no existing tests have been changed (albeit it would have been more correct to replace all `getStackByName` with `getStackArtifact`, but effectively this is the same thing if they are equal). We want the template file name to use the artifact ID instead of the physical stack name but this can break users that depend on this behaviour (despite the fact that it's a formal API). To avoid this, we will only enable this new behaviour behind a [feature flag](#4925) which means that it will only be enabled for new projects created through `cdk init`, but old projects will still get the old behaviour. RFC for feature flags: #4925 Fixes #4412 BREAKING CHANGE: template file names in `cdk.out` for new projects created by `cdk init` will use `stack.artifactId` instead of the physical stack name to enable multiple stacks to use the same name. In most cases the artifact ID is the same as the stack name. To enable this fix for old projects, add the context key `@aws-cdk/core:enableStackNameDuplicates: true` in your `cdk.json` file.
AWS CodeBuild CI Report
Powered by github-codebuild-logs, available on the AWS Serverless Application Repository |
…feature flag) (#4895) Since we used the stack name as the template file name, if users wanted to use the same stack name in two environments, the emitted templates overwrote each other. Furthermore, the CLI used the artifact ID as the stack name, so this became a bit more complex. This means that `assembly.getStack()` is now ambiguous, so I renamed it `getStackByName` which fails if there are two stacks with the same name (legitimate) and added `getStackArtifact` which uses the artifact ID. The core library will effectively generate identical cloud assemblies if the stack name and artifact IDs are the same, and to ensure backwards compat, no existing tests have been changed (albeit it would have been more correct to replace all `getStackByName` with `getStackArtifact`, but effectively this is the same thing if they are equal). We want the template file name to use the artifact ID instead of the physical stack name but this can break users that depend on this behaviour (despite the fact that it's a formal API). To avoid this, we will only enable this new behaviour behind a [feature flag](#4925) which means that it will only be enabled for new projects created through `cdk init`, but old projects will still get the old behaviour. RFC for feature flags: #4925 Fixes #4412 BREAKING CHANGE: template file names in `cdk.out` for new projects created by `cdk init` will use `stack.artifactId` instead of the physical stack name to enable multiple stacks to use the same name. In most cases the artifact ID is the same as the stack name. To enable this fix for old projects, add the context key `@aws-cdk/core:enableStackNameDuplicates: true` in your `cdk.json` file.
…feature flag) (#4895) Since we used the stack name as the template file name, if users wanted to use the same stack name in two environments, the emitted templates overwrote each other. Furthermore, the CLI used the artifact ID as the stack name, so this became a bit more complex. This means that `assembly.getStack()` is now ambiguous, so I renamed it `getStackByName` which fails if there are two stacks with the same name (legitimate) and added `getStackArtifact` which uses the artifact ID. The core library will effectively generate identical cloud assemblies if the stack name and artifact IDs are the same, and to ensure backwards compat, no existing tests have been changed (albeit it would have been more correct to replace all `getStackByName` with `getStackArtifact`, but effectively this is the same thing if they are equal). We want the template file name to use the artifact ID instead of the physical stack name but this can break users that depend on this behaviour (despite the fact that it's a formal API). To avoid this, we will only enable this new behaviour behind a [feature flag](aws/aws-cdk#4925) which means that it will only be enabled for new projects created through `cdk init`, but old projects will still get the old behaviour. RFC for feature flags: aws/aws-cdk#4925 Fixes #4412 BREAKING CHANGE: template file names in `cdk.out` for new projects created by `cdk init` will use `stack.artifactId` instead of the physical stack name to enable multiple stacks to use the same name. In most cases the artifact ID is the same as the stack name. To enable this fix for old projects, add the context key `@aws-cdk/core:enableStackNameDuplicates: true` in your `cdk.json` file.
Design proposal for a pattern/mechanism that will allow us to introduce
breaking capabilities which will only be applied to new projects created
by "cdk init" and won't break old projects without explicit action from the user.
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license