CONTRIBUTING.md

Contributing

To build and install terraform-cdk locally, Node version 12.16+

Getting Started

Clone the repository:

$ git clone https://github.com/hashicorp/terraform-cdk.git

To compile the terraform-cdk binary for your local machine:

$ yarn install
$ yarn build

Examples

We have a few top level script commands which are executed with Lerna to make the handling of examples easier:

yarn examples:reinstall // -> reinstall dependencies in Python examples
yarn examples:build // -> fetch providers for examples and build them
yarn examples:synth // -> synth all examples
yarn examples:integration // -> run all of the above

For this work, each example needs a package.json with at least a minmal config like this:

{
  "name": "@examples/[LANGUAGE]-[EXAMPLE_NAME]",
  "version": "0.0.0",
  "license": "MPL-2.0",
  "scripts": {
    "reinstall": "rm Pipfile.lock && pipenv --rm && pipenv install", // Python only
    "build": "cdktf get",
    "synth": "cdktf synth"
  }
}

Lerna is filtering for the @examples/ prefix in the name field.

Development

For development, you'd likely want to run:

$ yarn watch

This will watch for changes for the packages cdktf and cdktf-cli.

Tests

If you just want to run the tests:

$ yarn test

To run integration tests, package and run integration tests.

$ yarn package
$ yarn integration

Local Usage

Monorepo Examples

The easiest way to use this locally is using one of the examples. They are setup as part of the monorepo and reference the local packages.

Typescript

All Typescript examples leverage yarn workspaces to directly reference symlinked packages. If you don't have ./node_modules/.bin in your $PATH, you can use $(yarn bin)/cdktf to use the symlinked CLI.

Python

For Python examples, packages are referenced from ./dist, there's no symlinking possible for live code updates. You'll have to explictly run yarn package to create new packages to be referenced in the Pipefile.

Outside of this Monorepo

If you want to use the libraries and cli from the repo for local development, you can make use of yarn link.

Setup

Unfortunately, there's an issue with globally linked binaries. This requires you to run the following:

yarn config set prefix $(npm config get prefix)

If you'd want this permanently, you can add this line to your profile settings (~/.bashrc, ~/.zshrc, or ~/.profile, etc.)

Create link

Let's link cdktf and cdktf-cli, run the following the repository root folder:

$ yarn link-packages
$ cdktf --version
0.0.0

When the version equals 0.0.0 everything worked as expected. If you see another version, try uninstalling cdktf-cli with npm or yarn.

Build & Package

$ yarn build && yarn package
$ export CDKTF_DIST=$(pwd)/dist

Create local project

$ mkdir ~/my-local-cdktf-example
$ cd ~/my-local-cdktf-example
$ cdktf init --template typescript --local

Please note, that this will reference the built packages in $CDKTF_DIST. This means, it will reflect code changes only after repeating yarn build && yarn package and running an explicit yarn install again.

Reference the previously linked cdktf package in our newly created project:

$ cd ~/my-local-cdktf-example
$ yarn link "cdktf"

From here on both, the cli and the cdktf packages are linked and changes will be reflected immediatlely.

Rebasing contributions against master

PRs in this repo are merged using the rebase method. This keeps the git history clean by adding the PR commits to the most recent end of the commit history. It also has the benefit of keeping all the relevant commits for a given PR together, rather than spread throughout the git history based on when the commits were first created.

If the changes in your PR do not conflict with any of the existing code in the project, then Github supports automatic rebasing when the PR is accepted into the code. However, if there are conflicts (there will be a warning on the PR that reads "This branch cannot be rebased due to conflicts"), you will need to manually rebase the branch on master, fixing any conflicts along the way before the code can be merged.