chore(doc): update contributing guide (#25361)

Before running `yarn integ` it's required to build up the `framework-integ`, which is not mentioned in the doc and we are having error report from the [slack community](https://cdk-dev.slack.com/archives/C041656G340/p1682606764515889). - [x] add `Build framework-integ` section - [x] update gitpod section and suggest using AWS IAM Identity Center(AWS SSO) for AWS authentication - [x] add Amazon CodeCatalyst DevEnv as suggested dev environment as well - [x] some minor content fix and anchor link fix Closes #<issue number here>. ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
aws · May 2, 2023 · 53d24f1 · 53d24f1
1 parent 5bdb012
commit 53d24f1
Showing 1 changed file with 49 additions and 6 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -51,7 +51,7 @@ let us know if it's not up-to-date (even better, submit a PR with your  correcti
 
 The following steps describe how to set up the AWS CDK repository on your local machine.
 The alternative is to use [Gitpod](https://www.gitpod.io/), a Cloud IDE for your development.
-See [Gitpod section](#gitpod-alternative) on how to set up the CDK repo on Gitpod.
+See [Gitpod section](#gitpod) on how to set up the CDK repo on Gitpod.
 
 ### Setup
 
@@ -92,7 +92,7 @@ CDK can be found at the location `packages/aws-cdk-lib/aws-iam`.
 The repo also contains the `tools/` directory that holds custom build tooling (modeled as private npm packages)
 specific to the CDK.
 
-### Build
+### Building aws-cdk-lib
 
 The full build of all of the packages within the repository can take a few minutes, about 20  when all tests are run.
 Most contributions only require working on a single package, usually `aws-cdk-lib`. To build this package for the first
@@ -162,7 +162,7 @@ Please follow the [setup instructions](https://code.visualstudio.com/docs/remote
 
 With VS Code setup, you will be prompted to open the `aws-cdk` repo in a Dev Container, or you can choos "Dev Containers: Reopen in Container" from the VS Code command palette.
 
-### Gitpod (Alternative)
+### Gitpod
 
 You may also set up your local development environment using [Gitpod](http://gitpod.io) -
 a service that allows you to spin up an in-browser Visual Studio Code-compatible editor,
@@ -177,7 +177,22 @@ You can now work on your CDK repository, as described in the [Getting Started](#
 Gitpod is free for 50 hours per month - make sure to stop your workspace when you're done
 (you can always resume it later, and it won't need to run the build again).
 
-For Gitpod users only! The best way to supply CDK with your AWS credentials is to add them as
+For Gitpod users only! The best way to authenticate AWS in Gitpod is to use AWS IAM Identity Center(successor to AWS Single Sign-On). [Install AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html#getting-started-install-instructions) and configure it as follows:
+
+```shell
+# make sure AWS CLI v2 is in your $PATH
+$ aws --version
+# configure the AWS profile with SSO
+$ aws configure sso
+# login and authenticate
+$ aws sso login
+# verify your current identity
+$ aws sts get-caller-identity
+```
+
+Check out [this document](https://docs.aws.amazon.com/cli/latest/userguide/sso-configure-profile-token.html) for the details.
+
+Alternatively, supply CDK with your AWS credentials as
 [persisting environment variables](https://www.gitpod.io/docs/environment-variables).
 Adding them works as follows via terminal:
 
@@ -188,6 +203,26 @@ eval $(gp env -e AWS_DEFAULT_REGION=ZZZZZZZZ)
 eval $(gp env -e)
 ```
 
+### Amazon CodeCatalyst Dev Environments
+
+Dev Environments are cloud-based development environments. 
+[Amazon CodeCatalyst](https://aws.amazon.com/codecatalyst/) allows you to checkout your linked Github
+repositories in your Dev Environments with your favorite local IDEs such as VSCode or JetBrains.
+
+Build up `aws-cdk-lib` as well as `framework-integ` when you enter your Dev Env:
+
+```shell
+$ yarn install
+$ NODE_OPTIONS=--max-old-space-size=8192 npx lerna run build --scope=aws-cdk-lib --scope=@aws-cdk-testing/framework-integ
+```
+
+You may [configure your Dev Env](https://docs.aws.amazon.com/codecatalyst/latest/userguide/devenvironment-devfile.html) with the `devfile.yaml` to further customize your Dev Env for CDK development.
+
+Read the links below for more details: 
+- [Dev Environments in CodeCatalyst](https://docs.aws.amazon.com/codecatalyst/latest/userguide/devenvironment.html)
+- [Using GitHub repositories in CodeCatalyst](https://docs.aws.amazon.com/codecatalyst/latest/userguide/extensions-github.html)
+- [Setting up to use the AWS CLI with CodeCatalyst](https://docs.aws.amazon.com/codecatalyst/latest/userguide/set-up-cli.html)
+
 ## Pull Requests
 
 Below is a flow chart that describes how your PR may be treated by repository maintainers:
@@ -279,6 +314,14 @@ Integration tests perform a few functions in the CDK code base -
 3. (Optionally) Acts as a way to validate that constructs set up the CloudFormation resources as expected. A successful
    CloudFormation deployment does not mean that the resources are set up correctly.
 
+**Build framework-integ**
+
+You need to build the `framework-integ` before running the `yarn integ`
+
+```console
+$ npx lerna run build --scope=@aws-cdk-testing/framework-integ
+```
+
 **When are integration tests required?**
 
 The following list contains common scenarios where we _know_ that integration tests are required.
@@ -308,7 +351,7 @@ Examples:
 * [integ.destinations.ts](https://github.com/aws/aws-cdk/blob/master/packages/%40aws-cdk/aws-lambda-destinations/test/integ.destinations.ts#L7)
 * [integ.put-events.ts](https://github.com/aws/aws-cdk/blob/main/packages/%40aws-cdk/aws-stepfunctions-tasks/test/eventbridge/integ.put-events.ts)
 
-**What do do if you cannot run integration tests**
+**What if you cannot run integration tests**
 
 If you are working on a PR that requires an update to an integration test and you are unable
 to run the `cdk-integ` tool to perform a real deployment, please call this out on the pull request
@@ -429,7 +472,7 @@ $ yarn integ --directory test/aws-eks/test
 Or run a specific integ test:
 
 ```console
-$ yarn integ --directory test/aws-eks/test/integ.name.js
+$ yarn integ test/aws-eks/test/integ.name.js
 ```
 
 See the [integration test guide](./INTEGRATION_TESTS.md) for a more complete guide on running