contributing.md

Contributing

This is a Python CDK project.

Environment Set-up

To start developing you can use our Taskfile to run run install or run env

Or you can do this step by step:

Create a virtualenv:

python3 -m venv venv

Activate virtualenv

Use the following to activate the newly created virtualenv:

source venv/bin/activate

If you are using Windows platform, you would activate the virtualenv like this:

venv\Scripts\activate.bat

Install dependencies

Once the virtualenv is activated, you can install the required dependencies:

pip install pip-tools
pip-sync

Synthetize template

At this point you can now synthesize the CloudFormation template for this project:

cdk synth

Code formatting

This project is using black to handle formatting.

Install black:

brew install black

Format all files:

black .

There are also editor integrations available. The file watcher for PyCharm/Intellij works well for auto-formatting on file save.

Pre-commit integration

If you are a frequent contributor, you should setup the pre-commit integration. From within this project's directory, run:

brew install pre-commit
pre-commit install

Now various checks, import sorting and formatting will be done on git commit. To run manually on all files, use this:

pre-commit run --all-files

If you want to know where pre-commit installs the tools it uses, see this section on how pre-commit handles caching.

Dependency management

This project uses pip-tools to manage dependencies. The following commands require the virtualenv to be active:

source venv/bin/activate

There are two primary workflows, update and sync.

Update

To update dependencies, modify requirements.in file. Generally requirements get pinned in this file for simplicity. After that, run:

pip-compile --upgrade --no-emit-index-url

This will update requirements.txt.

Sync

The sync command will sync requirements.txt with the virtualenv:

pip-sync

Useful CDK commands

• cdk ls list all stacks in the app
• cdk synth emits the synthesized CloudFormation template
• cdk deploy deploy this stack to your default AWS account/region
• cdk diff compare deployed stack with current state
• cdk docs open CDK documentation