cx-api: @aws-cdk/core:defaultCrossStackReferences documentation doesn't match behavior
- Dominant language
- TypeScript
- Stars
- 12.9k
- Forks
- 4.6k
- Avg merge
- 2d 3h
- Merged PRs (30d)
- 83
Description
### Describe the issue
The FEATURE_FLAGS.md documentation is misleading about the impact of updating the `@aws-cdk/core:defaultCrossStackReferences` configuration:
1. In the tables it is described as "Controls whether **cross-region** stack references are strong, weak, or both" (emphasis mine)
https://github.com/aws/aws-cdk/blob/6d65180e8cba96748e48795c7b3403f3f308ca6e/packages/aws-cdk-lib/cx-api/FEATURE_FLAGS.md?plain=1#L118
https://github.com/aws/aws-cdk/blob/6d65180e8cba96748e48795c7b3403f3f308ca6e/packages/aws-cdk-lib/cx-api/FEATURE_FLAGS.md?plain=1#L270
2. In the dedicated section, it states the same summary as the tables and goes even further to state that "This setting **only affects same-account, cross-region references**. Cross-account references are always weak, and **same-region references are always strong (Fn::ImportValue)**."
https://github.com/aws/aws-cdk/blob/6d65180e8cba96748e48795c7b3403f3f308ca6e/packages/aws-cdk-lib/cx-api/FEATURE_FLAGS.md?plain=1#L2474
https://github.com/aws/aws-cdk/blob/6d65180e8cba96748e48795c7b3403f3f308ca6e/packages/aws-cdk-lib/cx-api/FEATURE_FLAGS.md?plain=1#L2478-L2481
Based on my personal testing and review of the code, I believe that these pieces of documentation are incorrect -- the `resolveValue` implementation in core/lib/private/refs.ts specifically accounts for strength (as an aside, the initial code-level comment is at odds with the implementation):
https://github.com/aws/aws-cdk/blob/6d65180e8cba96748e48795c7b3403f3f308ca6e/packages/aws-cdk-lib/core/lib/private/refs.ts#L282-L301
This appears to be intentional as this was implemented/merged in #37824, we just failed to update the FEATURE_FLAGS.md accordingly.
### Links
https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk-lib/cx-api/FEATURE_FLAGS.md
Contributor guide
Research direction
Start with packages/aws-cdk-lib/cx-api/FEATURE_FLAGS.md, especially the tables and the dedicated defaultCrossStackReferences section, then compare its wording with resolveValue in packages/aws-cdk-lib/core/lib/private/refs.ts. Update the documentation so it matches the implemented reference behavior and the described scope of the setting.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 75/100