Environment Preparation for AWS CDK Pull Request

Published:
  Lastmod: 2023-01-17
by Ernest Chiang

(Illustration: The chef on the yacht is preparing salads for the guests one by one. In the process of preparing the environment required for CDK PR, we need to yarn build each package one by one. Image source: by wreindl.)

While watching Pahud’s video EP27 - (English)Create Your First AWS CDK Pull Request(4K 2160p) take notes for future use. The environment I am using when I take this notes is: macOS Catalina (10.15.6), installed with homebrew, zsh, nvm, docker.

Contributing Guideline

Preparation

fork aws-cdk

Fork aws/aws-cdk on GitHub, and git clone to my laptop.

install yarn & yarn install

Install yarn on macOS. I have already had nvm on my environment, so I use:

curl -o- -L https://yarnpkg.com/install.sh | bash

Switch to the project folder where I did git clone fork and execute:

yarn install

yarn build

I follow Pahud’s way to proceed yarn build with docker. The only difference between my environment and Pahud’s video is using zsh in my case:

docker run -it -e HOME=/tmp -u $(id -u) -w /app \
-v $PWD:/app \
-v /etc/passwd:/etc/passwd \
-v /var/run/docker.sock:/var/run/docker.sock \
--entrypoint='' jsii/superchain ./build.sh --skip-test

If you’re using bash, please replace $(id -u) above to be ${id -u}.

Then, wait for a long moment. In the process, it was colorful and pretty. I left the build and went to sleep and skip this long-waiting part XD

CDK L1 Construct

  • *.generated is generated for CDK L1 Construct library Cfn* prefix based on CloudFormation spec.

Finding Issues/PR

  • Get back to aws/aws-cdk. Using keywords to see if there’s any topic we are interested in GitHub Repo Issues. For example: ecs capacity provider. Find and see if there is existing issues.
  • Do checkout the guideline, ground rules and formats.
    • feat() = feature
    • chore() = chore
    • fix() = fix
    • (Using L2 construct name by ignoring prefix aws-)

Getting started

The following are the examples given in Pahud’s video to take notes, which happens to be the topic of ECS Capacity Provider that I like very much.

Remember to open a new branch from the master branch for everything you want to do. For example:

git checkout ecs-capacity-provider-l2

Go to @aws-cdk/aws-ecs or the directory you want to code.

Two directories, lib/ and test/, are mainly used.

  • Write integration test first, and then add or modify it in lib/ during the development process.
    • See the beginning of integ. in integ.xxx-xxx.ts, which represents integration test. (It is not necessary to create a new one every time, depending on the size of the new or modified scope.)
    • See the beginning of test. in test.xxx-xxx.ts, which represents unit test.
  • You can use relative paths to import your own lib/.
    • e.g. import * as ecs from '../../lib;'
  • During development, it’s recommended to have a second terminal window:
    • cd packages/@aws-cdk/aws-ecs
    • npm runwatch
    • Our goal is seeing Found 0 errors on last line.
  • Test deployment on the first terminal window:
    • cd packages/@aws-cdk/aws-ecs
    • cdk --app 'test/xxx/integ.xxx-xxx.js' diff, check diff first
    • cdk --app 'test/xxx/integ.xxx-xxx.js' deploy, then deploy it to actually see the result
  • Verification & Test
    • Generate integ.xxx-xxx.expected.json file.
    • The way to generate this integ.xxx-xxx.expected.json file is using: yarn integ xxx/integ.xxx-xxx.js
      • For example: When you start typing, you can quickly complete yarn integ test/ec2/integ.capacity-provider.js with tabs, then delete test/ and leave yarn integ ec2/integ.capacity-provider.js for execution.
    • Finally use yarn test to check all unit test and integ test. (Pahud will record another episode explaining the unit test in the future.)

Pull request

  • Same as the usual PR process, omitted. (Please refer to Getting merged by c9s for further reading).
  • Remember that the content description when posting a PR should follow the format and mention the issue number. Write more to help reviewer understand.

Reference