(aws-cdk): cdk deploy documentation doesn't mention concurrent deploys

[shellscape]

I opened #14316 recently, which was unceremoniously closed without further discussion around the crux of the problem. As @rix0rrr mentioned, there's a workaround for that particular problem, and his response would suggest that this is a known limitation of the framework at the moment.

Looking into the documentation in this repo, I can only find one mention of the flag here: https://github.com/aws/aws-cdk/tree/master/packages/aws-cdk#externally-executable-cloudformation-change-sets, which is a completely separate context and doesn't mention concurrent deployments via cdk deploy. #13024 added --change-set-name to the CLI, but the documentation doesn't mention other use cases for this flag.

The developer guide makes no mention of this flag, nor concurrent/parallel deployments https://docs.aws.amazon.com/cdk/latest/guide/cli.html and I'll raise a separate issue with them, pointing here.

This is a pretty big gap in the docs, and I'm honestly surprised that it hasn't been raised before with the increased commonality of monorepos for services and backend management. I'd like to suggest adding documentation to the README outlining known issues with parallel deployments, and pointing to using the --change-set-name flag to resolve the problem mentioned in the original bug issue.

---

This is a 📕 documentation issue

[rix0rrr]

Parallel deployments are not possible. CloudFormation doesn't support it: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-changesets.html

It's fair to say this limitation should have been mentioned in the docs. I will forward the ticket.

[github-actions]

This issue has not received any attention in 1 year. If you want to keep this issue open, please leave a comment below and auto-close will be canceled.

[shellscape]

@jerry-aws @peterwoodworth @NGL321 given that @rix0rrr stated that it should be mentioned in the docs and the ticket was assigned, should this not be reopened?

[shellscape]

@pahud this just came up on Twitter again as an issue. what's the good word?

[pahud]

@shellscape Thank you for bringing this up to our attention.

Can you share the Twitter link?

I'd like to suggest adding documentation to the README outlining known issues with parallel deployments, and pointing to using the --change-set-name flag to resolve the problem mentioned in the original bug issue.

Reading this issue thread, looks like the last consensus is to add relevant description in the document. We should take actions, are you interested to submit a doc update PR to address that? I believe the maintainer would be happy to provide suggested changes based on your PR words and move it forward. What do you think?

[shellscape]

@pahud https://x.com/shellscape/status/1816120368525873593

[pahud]

@shellscape

Thank you. I read the tweets. If you still think we should add/improve relevant document as you mentioned in this issue description. Please kindly submit a PR to address this issue, I will bring this up to the team and make sure we move it forward.

[shellscape]

respectfully, I'm not the right person to write that documentation. I lack the knowledge of the internals, the reasoning, or the alternatives.

[pahud]

@shellscape no worries, it doesn't have to be perfect. We just need to know what you expect to see in the README and a draft PR would be a perfect thing to get it started and make sure this stays in the backlog of the team.