aws / aws/aws-cdk

cx-api: @aws-cdk/core:defaultCrossStackReferences documentation doesn't match behavior

Open Beginner friendly
#38,503 6 comments 0 reactions 0 assignees View on GitHub
@aws-cdk/cx-api documentation effort/small p2
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.