Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(doc): update contributing guide #25361

Merged
merged 5 commits into from
May 2, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 49 additions & 6 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand All @@ -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:

Expand All @@ -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:
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down