From ae423e3223d905a3d3eaa22c6a0b271a655f9b48 Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Sun, 29 Mar 2020 14:13:42 +0300
Subject: [PATCH 01/34] added regression tests ability

---
 packages/aws-cdk/test/integ/cli.exclusions.js | 54 ++++++++++++++++++
 packages/aws-cdk/test/integ/cli/common.bash   | 27 ++++++---
 .../test/integ/cli/test-cdk-assembly.sh       |  2 +-
 packages/aws-cdk/test/integ/cli/test.sh       | 26 +++++++++
 packages/aws-cdk/test/integ/run-against-repo  | 15 +++++
 .../aws-cdk/test/integ/test-cli-backwards.sh  | 55 +++++++++++++++++++
 .../aws-cdk/test/integ/test-cli-framework.sh  |  4 ++
 7 files changed, 174 insertions(+), 9 deletions(-)
 create mode 100644 packages/aws-cdk/test/integ/cli.exclusions.js
 create mode 100755 packages/aws-cdk/test/integ/test-cli-backwards.sh
 create mode 100755 packages/aws-cdk/test/integ/test-cli-framework.sh

diff --git a/packages/aws-cdk/test/integ/cli.exclusions.js b/packages/aws-cdk/test/integ/cli.exclusions.js
new file mode 100644
index 0000000000000..f2fbd2fdb20e3
--- /dev/null
+++ b/packages/aws-cdk/test/integ/cli.exclusions.js
@@ -0,0 +1,54 @@
+/**
+List of exclusions when running backwards compatibility tests.
+Add when you need to exclude a specific integration test from a specific version.
+
+This is an escape hatch for the rare cases where we need to intorduce
+a change that breaks existing integration tests. (e.g security)
+
+For example:
+
+{
+    "test": "test-cdk-iam-diff.sh",
+    "version": "1.30.0",
+    "justification": "iam policy generation has changed in version > 1.30.0 because..."
+},
+
+*/
+const exclusions = []
+
+function getExclusion(test, version) {
+
+    const filtered = exclusions.filter(e => {
+        return e.test === test && e.version === version;
+    });
+
+    if (filtered.length === 0) {
+        return undefined;
+    }
+
+    if (filtered.length === 1) {
+        return filtered[0];
+    }
+
+    throw new Error(`Multiple exclusions found for (${test, version}): ${filtered.length}`);
+
+}
+
+module.exports.shouldSkip = function (test, version) {
+
+    const exclusion = getExclusion(test, version);
+
+    return exclusion != undefined
+
+}
+
+module.exports.getJustification = function (test, version) {
+
+    const exclusion = getExclusion(test, version);
+
+    if (!exclusion) {
+        throw new Error(`Exclusion not found for (${test}, ${version})`);
+    }
+
+    return exclusion.justification;
+}
diff --git a/packages/aws-cdk/test/integ/cli/common.bash b/packages/aws-cdk/test/integ/cli/common.bash
index 690ef418f6ca5..73dc917a5c282 100644
--- a/packages/aws-cdk/test/integ/cli/common.bash
+++ b/packages/aws-cdk/test/integ/cli/common.bash
@@ -2,6 +2,8 @@ set -eu
 scriptdir=$(cd $(dirname $0) && pwd)
 cd ${scriptdir}
 
+USE_PUBLISHED_FRAMEWORK_VERSION=${USE_PUBLISHED_FRAMEWORK_VERSION:-}
+
 if [[ -z "${CREDS_SET:-}" ]]; then
     # Check that credentials are configured (will error & abort if not)
     creds=$(aws sts get-caller-identity)
@@ -71,15 +73,24 @@ function prepare_fixture() {
     # we install locally.
     mkdir -p node_modules
 
+    # this will cause the npm wrapper to install
+    # the versions from source.
+    framework_version=""
+    if [ ! -z ${USE_PUBLISHED_FRAMEWORK_VERSION} ]; then
+      # this will cause the npm wrapper to install
+      # the latest published 1.x versions.
+      framework_version="@^1"
+    fi
+
     npm install \
-        @aws-cdk/core@^1 \
-        @aws-cdk/aws-sns@^1 \
-        @aws-cdk/aws-iam@^1 \
-        @aws-cdk/aws-lambda@^1 \
-        @aws-cdk/aws-ssm@^1 \
-        @aws-cdk/aws-ecr-assets@^1 \
-        @aws-cdk/aws-cloudformation@^1 \
-        @aws-cdk/aws-ec2@^1
+        @aws-cdk/core${framework_version} \
+        @aws-cdk/aws-sns${framework_version} \
+        @aws-cdk/aws-iam${framework_version} \
+        @aws-cdk/aws-lambda${framework_version} \
+        @aws-cdk/aws-ssm${framework_version} \
+        @aws-cdk/aws-ecr-assets${framework_version} \
+        @aws-cdk/aws-cloudformation${framework_version} \
+        @aws-cdk/aws-ec2${framework_version}
 
     echo "| setup complete at: $PWD"
     echo "| 'cdk' is: $(type -p cdk)"
diff --git a/packages/aws-cdk/test/integ/cli/test-cdk-assembly.sh b/packages/aws-cdk/test/integ/cli/test-cdk-assembly.sh
index ae3523b0b22fe..3a43e26cdd6c5 100755
--- a/packages/aws-cdk/test/integ/cli/test-cdk-assembly.sh
+++ b/packages/aws-cdk/test/integ/cli/test-cdk-assembly.sh
@@ -58,4 +58,4 @@ cdk -a . deploy "${STACK_NAME_PREFIX}-docker-with-custom-file" --require-approva
 # destory
 announce "cdk destroy"
 cdk -a . destroy -f "${STACK_NAME_PREFIX}-lambda"
-# cdk -a . destroy -f "${STACK_NAME_PREFIX}-docker"
+cdk -a . destroy -f "${STACK_NAME_PREFIX}-docker-with-custom-file"
diff --git a/packages/aws-cdk/test/integ/cli/test.sh b/packages/aws-cdk/test/integ/cli/test.sh
index 51aba309482ce..ecb0875fd10bc 100755
--- a/packages/aws-cdk/test/integ/cli/test.sh
+++ b/packages/aws-cdk/test/integ/cli/test.sh
@@ -7,9 +7,35 @@ header CLI Integration Tests
 
 prepare_fixture
 
+current_version=$(node -p "require('${scriptdir}/../../../package.json').version")
+
+VERSION_UNDER_TEST=${VERSION_UNDER_TEST:-${current_version}}
+
+function should_skip {
+  test=$1
+  echo $(node -p "require('${scriptdir}/../cli.exclusions.js').shouldSkip('${test}', '${VERSION_UNDER_TEST}')")
+}
+
+function get_skip_jusitification {
+  test=$1
+  echo $(node -p "require('${scriptdir}/../cli.exclusions.js').getJustification('${test}', '${VERSION_UNDER_TEST}')")
+}
+
 for test in $(cd ${scriptdir} && ls test-*.sh); do
   echo "============================================================================================"
+
+  skip=$(should_skip ${test})
+
+  if [ ${skip} == "true" ]; then
+
+    jusitification="$(get_skip_jusitification ${test})"
+
+    echo "${test} - skipped (${jusitification})"
+    continue
+  fi
+
   echo "${test}"
   echo "============================================================================================"
   /bin/bash ${scriptdir}/${test}
 done
+
diff --git a/packages/aws-cdk/test/integ/run-against-repo b/packages/aws-cdk/test/integ/run-against-repo
index 601097c880d18..757399fb5cec5 100755
--- a/packages/aws-cdk/test/integ/run-against-repo
+++ b/packages/aws-cdk/test/integ/run-against-repo
@@ -8,6 +8,14 @@ set -eu
 cli_dir=$(cd $(dirname $0)/../.. && pwd)
 repo_root=$(cd $cli_dir/../.. && pwd)
 
+# function unpatch_cli_version {
+#   sed -i '' -e 's/"version": "999.0.0"/"version": "0.0.0"/g' ${cli_dir}/package.json
+# }
+
+# function patch_cli_version {
+#   sed -i '' -e 's/"version": "0.0.0"/"version": "999.0.0"/g' ${cli_dir}/package.json
+# }
+
 if [[ ! -f $repo_root/package.json ]]; then
     echo "$repo_root does not seem to be the root of the aws-cdk repository." >&2
     exit 1
@@ -18,4 +26,11 @@ export ORIGINAL_NPM="$(type -p npm)"
 
 export PATH="$cli_dir/bin:$cli_dir/test/integ/run-wrappers/repo:$PATH"
 hash -r
+
+trap unpatch_cli_version INT EXIT
+
+# path cli version so simulate published state where cli >= framework.
+# this is really nasty, not sure of a reasonable better solution for now.
+# patch_cli_version
+
 exec "$@"
diff --git a/packages/aws-cdk/test/integ/test-cli-backwards.sh b/packages/aws-cdk/test/integ/test-cli-backwards.sh
new file mode 100755
index 0000000000000..8fd7113e686a7
--- /dev/null
+++ b/packages/aws-cdk/test/integ/test-cli-backwards.sh
@@ -0,0 +1,55 @@
+#!/bin/bash
+set -euo pipefail
+integdir=$(cd $(dirname $0) && pwd)
+
+temp_dir=$(mktemp -d)
+
+function cleanup {
+    rm -rf ${temp_dir}
+    rm -rf ${integ_under_test}
+}
+
+function get_latest_published_version {
+
+    github_headers=""
+    if [[ "${GITHUB_TOKEN:-}" != "" ]]; then
+        github_headers="Authorization: token ${GITHUB_TOKEN}"
+    fi
+
+    out="${temp_dir}/aws-cdk-release.json"
+
+    curl -Ss --dump-header /dev/null -H "$github_headers" https://api.github.com/repos/aws/aws-cdk/releases/latest > ${out}
+    latest_version=$(node -p "require('${out}').name")
+    echo ${latest_version}
+}
+
+function download_repo {
+
+    version=$1
+
+    out="${temp_dir}/.repo.tar.gz"
+
+    curl -L -o ${out} "https://github.com/aws/aws-cdk/archive/${version}.tar.gz"
+    tar --strip-components=1 -zxf ${out} -C ${temp_dir}
+    echo ${temp_dir}
+
+}
+
+VERSION_UNDER_TEST=${VERSION_UNDER_TEST:-$(get_latest_published_version)}
+
+trap cleanup INT EXIT
+
+echo "Downloading aws-cdk repo version ${VERSION_UNDER_TEST}"
+temp_repo_dir="$(download_repo ${VERSION_UNDER_TEST})"
+
+# remove '/' that is prevelant in our branch names but causes
+# bad behvaior when using it as directory names.
+sanitized_version=$(sed 's/\//-/g' <<< "${VERSION_UNDER_TEST}")
+
+integ_under_test=${integdir}/cli-backwards-tests-${sanitized_version}
+rm -rf ${integ_under_test}
+echo "Copying integration tests of version ${VERSION_UNDER_TEST} to ${integ_under_test} (dont worry, its gitignored)"
+cp -r ${temp_dir}/packages/aws-cdk/test/integ/cli ${integ_under_test}
+
+echo "Running integration tests of version ${VERSION_UNDER_TEST} from ${integ_under_test}"
+VERSION_UNDER_TEST=${VERSION_UNDER_TEST} ${integ_under_test}/test.sh
\ No newline at end of file
diff --git a/packages/aws-cdk/test/integ/test-cli-framework.sh b/packages/aws-cdk/test/integ/test-cli-framework.sh
new file mode 100755
index 0000000000000..bb0e6dc9e8ad5
--- /dev/null
+++ b/packages/aws-cdk/test/integ/test-cli-framework.sh
@@ -0,0 +1,4 @@
+#!/bin/bash
+set -euo pipefail
+integdir=$(cd $(dirname $0) && pwd)
+USE_PUBLISHED_FRAMEWORK_VERSION=True ${integdir}/test-cli-backwards.sh

From bd30a4d17758be5538f57ce8f901e74e04dd1c7a Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Sun, 29 Mar 2020 14:19:28 +0300
Subject: [PATCH 02/34] revert changes to test-cdk-assembly.sh

---
 packages/aws-cdk/test/integ/cli/test-cdk-assembly.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/aws-cdk/test/integ/cli/test-cdk-assembly.sh b/packages/aws-cdk/test/integ/cli/test-cdk-assembly.sh
index 3a43e26cdd6c5..ae3523b0b22fe 100755
--- a/packages/aws-cdk/test/integ/cli/test-cdk-assembly.sh
+++ b/packages/aws-cdk/test/integ/cli/test-cdk-assembly.sh
@@ -58,4 +58,4 @@ cdk -a . deploy "${STACK_NAME_PREFIX}-docker-with-custom-file" --require-approva
 # destory
 announce "cdk destroy"
 cdk -a . destroy -f "${STACK_NAME_PREFIX}-lambda"
-cdk -a . destroy -f "${STACK_NAME_PREFIX}-docker-with-custom-file"
+# cdk -a . destroy -f "${STACK_NAME_PREFIX}-docker"

From 945121c05a61c66ccec3acfdb2483de6c94c24cd Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Sun, 29 Mar 2020 14:21:26 +0300
Subject: [PATCH 03/34] remove version patching - not needed anymore

---
 packages/aws-cdk/test/integ/run-against-repo | 14 --------------
 1 file changed, 14 deletions(-)

diff --git a/packages/aws-cdk/test/integ/run-against-repo b/packages/aws-cdk/test/integ/run-against-repo
index 757399fb5cec5..1e3b671a036a4 100755
--- a/packages/aws-cdk/test/integ/run-against-repo
+++ b/packages/aws-cdk/test/integ/run-against-repo
@@ -8,14 +8,6 @@ set -eu
 cli_dir=$(cd $(dirname $0)/../.. && pwd)
 repo_root=$(cd $cli_dir/../.. && pwd)
 
-# function unpatch_cli_version {
-#   sed -i '' -e 's/"version": "999.0.0"/"version": "0.0.0"/g' ${cli_dir}/package.json
-# }
-
-# function patch_cli_version {
-#   sed -i '' -e 's/"version": "0.0.0"/"version": "999.0.0"/g' ${cli_dir}/package.json
-# }
-
 if [[ ! -f $repo_root/package.json ]]; then
     echo "$repo_root does not seem to be the root of the aws-cdk repository." >&2
     exit 1
@@ -27,10 +19,4 @@ export ORIGINAL_NPM="$(type -p npm)"
 export PATH="$cli_dir/bin:$cli_dir/test/integ/run-wrappers/repo:$PATH"
 hash -r
 
-trap unpatch_cli_version INT EXIT
-
-# path cli version so simulate published state where cli >= framework.
-# this is really nasty, not sure of a reasonable better solution for now.
-# patch_cli_version
-
 exec "$@"

From 29d05c6a7d37101552eaf774554136661d8e3781 Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Sun, 29 Mar 2020 14:22:28 +0300
Subject: [PATCH 04/34] remove blank line

---
 packages/aws-cdk/test/integ/run-against-repo | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/aws-cdk/test/integ/run-against-repo b/packages/aws-cdk/test/integ/run-against-repo
index 1e3b671a036a4..601097c880d18 100755
--- a/packages/aws-cdk/test/integ/run-against-repo
+++ b/packages/aws-cdk/test/integ/run-against-repo
@@ -18,5 +18,4 @@ export ORIGINAL_NPM="$(type -p npm)"
 
 export PATH="$cli_dir/bin:$cli_dir/test/integ/run-wrappers/repo:$PATH"
 hash -r
-
 exec "$@"

From 190793fc868885a1ed1d895e5164262feb5980a2 Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Sun, 29 Mar 2020 16:35:13 +0300
Subject: [PATCH 05/34] fix npm local wrapper to support using latest published
 framework

---
 .gitignore                                    |  2 ++
 packages/aws-cdk/package.json                 |  2 ++
 packages/aws-cdk/test/integ/cli/common.bash   | 25 ++++++-------------
 packages/aws-cdk/test/integ/cli/test.sh       |  2 +-
 .../aws-cdk/test/integ/run-wrappers/repo/npm  |  6 ++---
 tools/prlint/package.json                     |  3 +++
 6 files changed, 19 insertions(+), 21 deletions(-)

diff --git a/.gitignore b/.gitignore
index 17ba70d7ac568..e2f6e2d4fe3c5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,7 @@
 # VSCode extension
 .vscode/
+.history/
+
 /.favorites.json
 
 # TypeScript incremental build states
diff --git a/packages/aws-cdk/package.json b/packages/aws-cdk/package.json
index 24ab9cde20186..5e620fae95c0f 100644
--- a/packages/aws-cdk/package.json
+++ b/packages/aws-cdk/package.json
@@ -18,6 +18,8 @@
     "build+test+package": "npm run build+test && npm run package",
     "build+test": "npm run build && npm test",
     "integ-cli": "test/integ/run-against-repo test/integ/cli/test.sh",
+    "integ-cli-backwards": "test/integ/run-against-repo test/integ/test-cli-backwards.sh",
+    "integ-cli-framework": "test/integ/run-against-repo test/integ/test-cli-framework.sh",
     "integ-init": "test/integ/run-against-dist test/integ/init/test-all.sh"
   },
   "cdk-build": {
diff --git a/packages/aws-cdk/test/integ/cli/common.bash b/packages/aws-cdk/test/integ/cli/common.bash
index 73dc917a5c282..395f14ba6931c 100644
--- a/packages/aws-cdk/test/integ/cli/common.bash
+++ b/packages/aws-cdk/test/integ/cli/common.bash
@@ -73,24 +73,15 @@ function prepare_fixture() {
     # we install locally.
     mkdir -p node_modules
 
-    # this will cause the npm wrapper to install
-    # the versions from source.
-    framework_version=""
-    if [ ! -z ${USE_PUBLISHED_FRAMEWORK_VERSION} ]; then
-      # this will cause the npm wrapper to install
-      # the latest published 1.x versions.
-      framework_version="@^1"
-    fi
-
     npm install \
-        @aws-cdk/core${framework_version} \
-        @aws-cdk/aws-sns${framework_version} \
-        @aws-cdk/aws-iam${framework_version} \
-        @aws-cdk/aws-lambda${framework_version} \
-        @aws-cdk/aws-ssm${framework_version} \
-        @aws-cdk/aws-ecr-assets${framework_version} \
-        @aws-cdk/aws-cloudformation${framework_version} \
-        @aws-cdk/aws-ec2${framework_version}
+        @aws-cdk/core \
+        @aws-cdk/aws-sns \
+        @aws-cdk/aws-iam \
+        @aws-cdk/aws-lambda \
+        @aws-cdk/aws-ssm \
+        @aws-cdk/aws-ecr-assets \
+        @aws-cdk/aws-cloudformation \
+        @aws-cdk/aws-ec2
 
     echo "| setup complete at: $PWD"
     echo "| 'cdk' is: $(type -p cdk)"
diff --git a/packages/aws-cdk/test/integ/cli/test.sh b/packages/aws-cdk/test/integ/cli/test.sh
index ecb0875fd10bc..86d11ba99bb8e 100755
--- a/packages/aws-cdk/test/integ/cli/test.sh
+++ b/packages/aws-cdk/test/integ/cli/test.sh
@@ -36,6 +36,6 @@ for test in $(cd ${scriptdir} && ls test-*.sh); do
 
   echo "${test}"
   echo "============================================================================================"
-  /bin/bash ${scriptdir}/${test}
+  # /bin/bash ${scriptdir}/${test}
 done
 
diff --git a/packages/aws-cdk/test/integ/run-wrappers/repo/npm b/packages/aws-cdk/test/integ/run-wrappers/repo/npm
index 4a49bd85621b5..f6ee65754bd1a 100755
--- a/packages/aws-cdk/test/integ/run-wrappers/repo/npm
+++ b/packages/aws-cdk/test/integ/run-wrappers/repo/npm
@@ -5,7 +5,9 @@ command=$1
 
 lerna=$REPO_ROOT/node_modules/.bin/lerna
 
-if [[ "$command" == "install" || "$command" == "i" ]]; then
+if [ ! -z ${USE_PUBLISHED_FRAMEWORK_VERSION:-""} ]; then
+  exec $ORIGINAL_NPM "$@"
+elif [[ "$command" == "install" || "$command" == "i" ]]; then
   npmargs="install"
   shift
 
@@ -29,5 +31,3 @@ if [[ "$command" == "install" || "$command" == "i" ]]; then
 
   exec $ORIGINAL_NPM $npmargs
 fi
-
-exec $ORIGINAL_NPM "$@"
\ No newline at end of file
diff --git a/tools/prlint/package.json b/tools/prlint/package.json
index 30175eca33662..b51a6787878e4 100644
--- a/tools/prlint/package.json
+++ b/tools/prlint/package.json
@@ -9,6 +9,9 @@
     "name": "Amazon Web Services",
     "url": "https://aws.amazon.com"
   },
+  "scripts": {
+    "build": "echo success"
+  },
   "license": "Apache-2.0",
   "dependencies": {
     "github-api": "^3.3.0",

From 23dfb211ff6ca87bc888456bedc854a65e322ec3 Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Sun, 29 Mar 2020 16:36:17 +0300
Subject: [PATCH 06/34] cleanup

---
 packages/aws-cdk/test/integ/cli/common.bash       | 2 --
 packages/aws-cdk/test/integ/run-wrappers/repo/npm | 2 +-
 2 files changed, 1 insertion(+), 3 deletions(-)

diff --git a/packages/aws-cdk/test/integ/cli/common.bash b/packages/aws-cdk/test/integ/cli/common.bash
index 395f14ba6931c..1d828f2ccdb9e 100644
--- a/packages/aws-cdk/test/integ/cli/common.bash
+++ b/packages/aws-cdk/test/integ/cli/common.bash
@@ -2,8 +2,6 @@ set -eu
 scriptdir=$(cd $(dirname $0) && pwd)
 cd ${scriptdir}
 
-USE_PUBLISHED_FRAMEWORK_VERSION=${USE_PUBLISHED_FRAMEWORK_VERSION:-}
-
 if [[ -z "${CREDS_SET:-}" ]]; then
     # Check that credentials are configured (will error & abort if not)
     creds=$(aws sts get-caller-identity)
diff --git a/packages/aws-cdk/test/integ/run-wrappers/repo/npm b/packages/aws-cdk/test/integ/run-wrappers/repo/npm
index f6ee65754bd1a..aa2b8ca90ce37 100755
--- a/packages/aws-cdk/test/integ/run-wrappers/repo/npm
+++ b/packages/aws-cdk/test/integ/run-wrappers/repo/npm
@@ -5,7 +5,7 @@ command=$1
 
 lerna=$REPO_ROOT/node_modules/.bin/lerna
 
-if [ ! -z ${USE_PUBLISHED_FRAMEWORK_VERSION:-""} ]; then
+if [ ! -z ${USE_PUBLISHED_FRAMEWORK_VERSION:-} ]; then
   exec $ORIGINAL_NPM "$@"
 elif [[ "$command" == "install" || "$command" == "i" ]]; then
   npmargs="install"

From 7438634b334a8ca86dc4ff1667516fedcf02bcbb Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Sun, 29 Mar 2020 18:14:03 +0300
Subject: [PATCH 07/34] only publish CDK cli when using published framework

---
 packages/aws-cdk/test/integ/run-against-dist.bash | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/packages/aws-cdk/test/integ/run-against-dist.bash b/packages/aws-cdk/test/integ/run-against-dist.bash
index 10f70d965f37a..443c7a4db28e2 100644
--- a/packages/aws-cdk/test/integ/run-against-dist.bash
+++ b/packages/aws-cdk/test/integ/run-against-dist.bash
@@ -59,6 +59,11 @@ function serve_npm_packages() {
 
   use_verdaccio
 
+  if [ ! -z ${USE_PUBLISHED_FRAMEWORK_VERSION:-} ]; then
+    # when using latest published framework, only publish cli
+    tarballs=aws-cdk-*.tgz
+  fi
+
   log "Publishing NPM tarballs..."
   for tgz in $tarballs; do
     # Doesn't matter what directory it is, just shouldn't be the

From 9a93910ac3e226a06d35afba244cd90bc73720bd Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Sun, 29 Mar 2020 22:18:51 +0300
Subject: [PATCH 08/34] sanity check

---
 build.sh | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/build.sh b/build.sh
index b58fa80e1c563..ee19e0424eff3 100755
--- a/build.sh
+++ b/build.sh
@@ -1,6 +1,9 @@
 #!/bin/bash
 set -euo pipefail
 
+echo "Just sanity that this code is taken"
+exit 1
+
 bail="--bail"
 runtarget="build+test"
 while [[ "${1:-}" != "" ]]; do

From 7b093b92e5eed041d1230fc49df76adbe469abde Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Sun, 29 Mar 2020 22:22:13 +0300
Subject: [PATCH 09/34] dummy

---
 build.sh | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/build.sh b/build.sh
index ee19e0424eff3..fdeff1c159f70 100755
--- a/build.sh
+++ b/build.sh
@@ -1,9 +1,11 @@
 #!/bin/bash
 set -euo pipefail
 
+echo "dummy commit"
 echo "Just sanity that this code is taken"
 exit 1
 
+
 bail="--bail"
 runtarget="build+test"
 while [[ "${1:-}" != "" ]]; do

From 6cac03710f5ce553b517e55e3598b98f4106547b Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Sun, 29 Mar 2020 22:27:14 +0300
Subject: [PATCH 10/34] dummy

---
 build.sh | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/build.sh b/build.sh
index fdeff1c159f70..b58fa80e1c563 100755
--- a/build.sh
+++ b/build.sh
@@ -1,11 +1,6 @@
 #!/bin/bash
 set -euo pipefail
 
-echo "dummy commit"
-echo "Just sanity that this code is taken"
-exit 1
-
-
 bail="--bail"
 runtarget="build+test"
 while [[ "${1:-}" != "" ]]; do

From ed7cc03f78c3f4880d4d5796f70dbeb65efacc0d Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Sun, 29 Mar 2020 23:54:29 +0300
Subject: [PATCH 11/34] added some logs

---
 packages/aws-cdk/test/integ/run-against-dist.bash | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/packages/aws-cdk/test/integ/run-against-dist.bash b/packages/aws-cdk/test/integ/run-against-dist.bash
index 443c7a4db28e2..a22bbf932a023 100644
--- a/packages/aws-cdk/test/integ/run-against-dist.bash
+++ b/packages/aws-cdk/test/integ/run-against-dist.bash
@@ -59,11 +59,16 @@ function serve_npm_packages() {
 
   use_verdaccio
 
+  echo "Checking if using published framework"
+
   if [ ! -z ${USE_PUBLISHED_FRAMEWORK_VERSION:-} ]; then
     # when using latest published framework, only publish cli
+    echo "Yes, using published framework"
     tarballs=aws-cdk-*.tgz
   fi
 
+  echo "tarballs = ${tarballs}"
+
   log "Publishing NPM tarballs..."
   for tgz in $tarballs; do
     # Doesn't matter what directory it is, just shouldn't be the

From 0aa39c8c7c0402e66cef03132d10b6a1d15d922c Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Tue, 31 Mar 2020 00:00:26 +0300
Subject: [PATCH 12/34] fix tarball path

---
 packages/aws-cdk/test/integ/run-against-dist.bash | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/aws-cdk/test/integ/run-against-dist.bash b/packages/aws-cdk/test/integ/run-against-dist.bash
index a22bbf932a023..f8feaa0aa59bb 100644
--- a/packages/aws-cdk/test/integ/run-against-dist.bash
+++ b/packages/aws-cdk/test/integ/run-against-dist.bash
@@ -64,7 +64,7 @@ function serve_npm_packages() {
   if [ ! -z ${USE_PUBLISHED_FRAMEWORK_VERSION:-} ]; then
     # when using latest published framework, only publish cli
     echo "Yes, using published framework"
-    tarballs=aws-cdk-*.tgz
+    tarballs=$dist_root/js/aws-cdk*.tgz
   fi
 
   echo "tarballs = ${tarballs}"

From 434c2b55782f661b6de7af210b04a39531864b4d Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Tue, 31 Mar 2020 01:51:01 +0300
Subject: [PATCH 13/34] oh my

---
 .../aws-cdk/test/integ/run-against-dist.bash  | 49 ++++++++++++-------
 1 file changed, 31 insertions(+), 18 deletions(-)

diff --git a/packages/aws-cdk/test/integ/run-against-dist.bash b/packages/aws-cdk/test/integ/run-against-dist.bash
index f8feaa0aa59bb..174f4cbe9c49f 100644
--- a/packages/aws-cdk/test/integ/run-against-dist.bash
+++ b/packages/aws-cdk/test/integ/run-against-dist.bash
@@ -22,17 +22,38 @@ function serve_npm_packages() {
     return
   fi
 
-  tarballs=$dist_root/js/*.tgz
+  echo "Checking if using published framework"
 
-  log "Discovering local package names..."
-  # Read the package names from each tarball, so that we can generate
-  # a Verdaccio config that will keep each of these packages locally
-  # and not go to NPMJS for it.
-  package_names=""
-  for tgz in $tarballs; do
-    name=$(node -pe 'JSON.parse(process.argv[1]).name' "$(tar xOzf $tgz package/package.json)")
-    package_names="$package_names $name"
-  done
+  if [ ! -z ${USE_PUBLISHED_FRAMEWORK_VERSION:-} ]; then
+    # when using latest published framework, only
+    # install the cli and its dependencies.
+
+    echo "Looking up CLI dependencies..."
+    # good lord
+    package_names=$(node -p "Object.entries(require('./package/package.json').dependencies).filter(x => x[0].includes('@aws-cdk')).map(x => x[0] + '-${version}').join(' ')")
+
+    echo "Yes, using published framework"
+    version=$(node -p 'require("./package/package.json").version')
+    tarballs=$dist_root/js/aws-cdk-${version}.tgz
+    package_names="${package_names} aws-cdk-${version}"
+
+    echo "tarballs= ${tarballs}"
+    echo "package_names= ${package_names}"
+  else
+
+    tarballs=$dist_root/js/*.tgz
+
+    log "Discovering local package names..."
+    # Read the package names from each tarball, so that we can generate
+    # a Verdaccio config that will keep each of these packages locally
+    # and not go to NPMJS for it.
+    package_names=""
+    for tgz in $tarballs; do
+      name=$(node -pe 'JSON.parse(process.argv[1]).name' "$(tar xOzf $tgz package/package.json)")
+      package_names="$package_names $name"
+    done
+
+  fi
 
   #------------------------------------------------------------------------------
   # Start a local npm repository and install the CDK from the distribution to it
@@ -59,14 +80,6 @@ function serve_npm_packages() {
 
   use_verdaccio
 
-  echo "Checking if using published framework"
-
-  if [ ! -z ${USE_PUBLISHED_FRAMEWORK_VERSION:-} ]; then
-    # when using latest published framework, only publish cli
-    echo "Yes, using published framework"
-    tarballs=$dist_root/js/aws-cdk*.tgz
-  fi
-
   echo "tarballs = ${tarballs}"
 
   log "Publishing NPM tarballs..."

From f112b71e12b1a6b29b60d61c7640bfd9b47abd3f Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Tue, 31 Mar 2020 03:16:22 +0300
Subject: [PATCH 14/34] fix version

---
 packages/aws-cdk/test/integ/run-against-dist.bash | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/aws-cdk/test/integ/run-against-dist.bash b/packages/aws-cdk/test/integ/run-against-dist.bash
index 174f4cbe9c49f..2e9066fb32d68 100644
--- a/packages/aws-cdk/test/integ/run-against-dist.bash
+++ b/packages/aws-cdk/test/integ/run-against-dist.bash
@@ -28,12 +28,13 @@ function serve_npm_packages() {
     # when using latest published framework, only
     # install the cli and its dependencies.
 
+    version=$(node -p 'require("./package/package.json").version')
+
     echo "Looking up CLI dependencies..."
     # good lord
     package_names=$(node -p "Object.entries(require('./package/package.json').dependencies).filter(x => x[0].includes('@aws-cdk')).map(x => x[0] + '-${version}').join(' ')")
 
     echo "Yes, using published framework"
-    version=$(node -p 'require("./package/package.json").version')
     tarballs=$dist_root/js/aws-cdk-${version}.tgz
     package_names="${package_names} aws-cdk-${version}"
 

From a22c21512a1255ba7f09608295d872e032b281ea Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Tue, 31 Mar 2020 12:43:33 +0300
Subject: [PATCH 15/34] fix tarball construction

---
 .../aws-cdk/test/integ/run-against-dist.bash  | 24 ++++++++++++++++---
 1 file changed, 21 insertions(+), 3 deletions(-)

diff --git a/packages/aws-cdk/test/integ/run-against-dist.bash b/packages/aws-cdk/test/integ/run-against-dist.bash
index 2e9066fb32d68..ae1fdf527f223 100644
--- a/packages/aws-cdk/test/integ/run-against-dist.bash
+++ b/packages/aws-cdk/test/integ/run-against-dist.bash
@@ -22,24 +22,41 @@ function serve_npm_packages() {
     return
   fi
 
+  cli_root=./package  
+
   echo "Checking if using published framework"
 
   if [ ! -z ${USE_PUBLISHED_FRAMEWORK_VERSION:-} ]; then
     # when using latest published framework, only
     # install the cli and its dependencies.
 
-    version=$(node -p 'require("./package/package.json").version')
+    version=$(node -p "require('${cli_root}/package.json').version")
 
     echo "Looking up CLI dependencies..."
     # good lord
-    package_names=$(node -p "Object.entries(require('./package/package.json').dependencies).filter(x => x[0].includes('@aws-cdk')).map(x => x[0] + '-${version}').join(' ')")
+    cli_deps=$(node -p "Object.entries(require('${cli_root}/package.json').dependencies).filter(x => x[0].includes('@aws-cdk')).map(x => x[0].replace('@aws-cdk/', '')).join(' ')")
 
     echo "Yes, using published framework"
     tarballs=$dist_root/js/aws-cdk-${version}.tgz
-    package_names="${package_names} aws-cdk-${version}"
+    package_names="aws-cdk"
+
+    for dep in ${cli_deps}; do
+      
+      tarball=$dist_root/js/${dep}@${version}.jsii.tgz
+      package=@aws-cdk/${dep}
+      if [ ! -f ${tarball} ]; then
+        # not a jsii dependency, the tarball is different...
+        tarball=$dist_root/js/aws-cdk-${dep}-${version}.tgz        
+      fi 
+
+      ls -l ${tarball}
+      tarballs="${tarballs} ${tarball}"
+      package_names="${package_names} ${package}"
+    done
 
     echo "tarballs= ${tarballs}"
     echo "package_names= ${package_names}"
+
   else
 
     tarballs=$dist_root/js/*.tgz
@@ -89,6 +106,7 @@ function serve_npm_packages() {
     # aws-cdk package directory.
     (cd $npmws && npm --quiet publish $tgz)
   done
+
 }
 
 function write_verdaccio_config() {

From 91536df097a1fc8d99fd336bf8a2d11f3e2eeda7 Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Tue, 31 Mar 2020 21:38:28 +0300
Subject: [PATCH 16/34] perpand parameters value with stack prefix

---
 .../integ/cli/test-cdk-deploy-nested-stack-with-parameters.sh   | 2 +-
 .../test/integ/cli/test-cdk-deploy-wildcard-with-parameters.sh  | 2 +-
 .../aws-cdk/test/integ/cli/test-cdk-deploy-with-parameters.sh   | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/aws-cdk/test/integ/cli/test-cdk-deploy-nested-stack-with-parameters.sh b/packages/aws-cdk/test/integ/cli/test-cdk-deploy-nested-stack-with-parameters.sh
index f1ef447e416e4..e2c14d47520f9 100755
--- a/packages/aws-cdk/test/integ/cli/test-cdk-deploy-nested-stack-with-parameters.sh
+++ b/packages/aws-cdk/test/integ/cli/test-cdk-deploy-nested-stack-with-parameters.sh
@@ -6,7 +6,7 @@ source ${scriptdir}/common.bash
 
 setup
 
-stack_arn=$(cdk deploy -v ${STACK_NAME_PREFIX}-with-nested-stack-using-parameters --parameters "MyTopicParam=ThereIsNoSpoon")
+stack_arn=$(cdk deploy -v ${STACK_NAME_PREFIX}-with-nested-stack-using-parameters --parameters "MyTopicParam=${STACK_NAME_PREFIX}ThereIsNoSpoon")
 echo "Stack deployed successfully"
 
 # verify that we only deployed a single stack (there's a single ARN in the output)
diff --git a/packages/aws-cdk/test/integ/cli/test-cdk-deploy-wildcard-with-parameters.sh b/packages/aws-cdk/test/integ/cli/test-cdk-deploy-wildcard-with-parameters.sh
index ba5cc286416e5..ed75c4c195f77 100755
--- a/packages/aws-cdk/test/integ/cli/test-cdk-deploy-wildcard-with-parameters.sh
+++ b/packages/aws-cdk/test/integ/cli/test-cdk-deploy-wildcard-with-parameters.sh
@@ -6,7 +6,7 @@ source ${scriptdir}/common.bash
 
 setup
 
-stack_arns=$(cdk deploy ${STACK_NAME_PREFIX}-param-test-\* --parameters "${STACK_NAME_PREFIX}-param-test-1:TopicNameParam=bazinga" --parameters "${STACK_NAME_PREFIX}-param-test-2:OtherTopicNameParam=ThatsMySpot")
+stack_arns=$(cdk deploy ${STACK_NAME_PREFIX}-param-test-\* --parameters "${STACK_NAME_PREFIX}-param-test-1:TopicNameParam=${STACK_NAME_PREFIX}bazinga" --parameters "${STACK_NAME_PREFIX}-param-test-2:OtherTopicNameParam=${STACK_NAME_PREFIX}ThatsMySpot")
 echo "Stack deployed successfully"
 
 # verify that we only deployed a single stack (there's a single ARN in the output)
diff --git a/packages/aws-cdk/test/integ/cli/test-cdk-deploy-with-parameters.sh b/packages/aws-cdk/test/integ/cli/test-cdk-deploy-with-parameters.sh
index 0209de3d0af9f..9e162faac2a61 100755
--- a/packages/aws-cdk/test/integ/cli/test-cdk-deploy-with-parameters.sh
+++ b/packages/aws-cdk/test/integ/cli/test-cdk-deploy-with-parameters.sh
@@ -6,7 +6,7 @@ source ${scriptdir}/common.bash
 
 setup
 
-stack_arn=$(cdk deploy -v ${STACK_NAME_PREFIX}-param-test-1 --parameters "TopicNameParam=bazinga")
+stack_arn=$(cdk deploy -v ${STACK_NAME_PREFIX}-param-test-1 --parameters "TopicNameParam=${STACK_NAME_PREFIX}bazinga")
 echo "Stack deployed successfully"
 
 # verify that we only deployed a single stack (there's a single ARN in the output)

From 9d795e756c4c2ae0ffa5305a426d016908d00361 Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Sun, 29 Mar 2020 18:14:03 +0300
Subject: [PATCH 17/34] only publish CDK cli when using published framework


From 9d2840ba6f1c3e0d3575645dfb43167b0eacd7a8 Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Wed, 1 Apr 2020 00:47:43 +0300
Subject: [PATCH 18/34] remove .history from ignore

---
 .gitignore | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.gitignore b/.gitignore
index e2f6e2d4fe3c5..9c2629d9c398f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,5 @@
 # VSCode extension
 .vscode/
-.history/
 
 /.favorites.json
 

From 5292fa47e307b5f27e1941059f735e69b63d0d13 Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Wed, 1 Apr 2020 00:48:11 +0300
Subject: [PATCH 19/34] remove blank line

---
 .gitignore | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.gitignore b/.gitignore
index 9c2629d9c398f..17ba70d7ac568 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,5 @@
 # VSCode extension
 .vscode/
-
 /.favorites.json
 
 # TypeScript incremental build states

From 229f3e5a5c4e8af9a2aa5214d900a4616a6fba6e Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Wed, 1 Apr 2020 00:51:29 +0300
Subject: [PATCH 20/34] uncomment test

---
 packages/aws-cdk/test/integ/cli/test.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/aws-cdk/test/integ/cli/test.sh b/packages/aws-cdk/test/integ/cli/test.sh
index 86d11ba99bb8e..ecb0875fd10bc 100755
--- a/packages/aws-cdk/test/integ/cli/test.sh
+++ b/packages/aws-cdk/test/integ/cli/test.sh
@@ -36,6 +36,6 @@ for test in $(cd ${scriptdir} && ls test-*.sh); do
 
   echo "${test}"
   echo "============================================================================================"
-  # /bin/bash ${scriptdir}/${test}
+  /bin/bash ${scriptdir}/${test}
 done
 

From bc875e3273c0c4e30e5077280eb33c7337bb6504 Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Wed, 1 Apr 2020 01:02:15 +0300
Subject: [PATCH 21/34] tidy up

---
 .../aws-cdk/test/integ/run-against-dist.bash    | 17 +++++++----------
 1 file changed, 7 insertions(+), 10 deletions(-)

diff --git a/packages/aws-cdk/test/integ/run-against-dist.bash b/packages/aws-cdk/test/integ/run-against-dist.bash
index ae1fdf527f223..af7e98412a8fe 100644
--- a/packages/aws-cdk/test/integ/run-against-dist.bash
+++ b/packages/aws-cdk/test/integ/run-against-dist.bash
@@ -22,26 +22,25 @@ function serve_npm_packages() {
     return
   fi
 
-  cli_root=./package  
+  if [ ! -z ${USE_PUBLISHED_FRAMEWORK_VERSION:-} ]; then
 
-  echo "Checking if using published framework"
+    echo "Testing against latest published versions of the framework"
 
-  if [ ! -z ${USE_PUBLISHED_FRAMEWORK_VERSION:-} ]; then
     # when using latest published framework, only
     # install the cli and its dependencies.
 
+    cli_root=./package  
+
     version=$(node -p "require('${cli_root}/package.json').version")
 
-    echo "Looking up CLI dependencies..."
     # good lord
+    echo "Fetching CLI dependencies"
     cli_deps=$(node -p "Object.entries(require('${cli_root}/package.json').dependencies).filter(x => x[0].includes('@aws-cdk')).map(x => x[0].replace('@aws-cdk/', '')).join(' ')")
 
-    echo "Yes, using published framework"
     tarballs=$dist_root/js/aws-cdk-${version}.tgz
     package_names="aws-cdk"
 
     for dep in ${cli_deps}; do
-      
       tarball=$dist_root/js/${dep}@${version}.jsii.tgz
       package=@aws-cdk/${dep}
       if [ ! -f ${tarball} ]; then
@@ -49,16 +48,14 @@ function serve_npm_packages() {
         tarball=$dist_root/js/aws-cdk-${dep}-${version}.tgz        
       fi 
 
-      ls -l ${tarball}
       tarballs="${tarballs} ${tarball}"
       package_names="${package_names} ${package}"
     done
 
-    echo "tarballs= ${tarballs}"
-    echo "package_names= ${package_names}"
-
   else
 
+    echo "Testing against local versions of the framework"
+
     tarballs=$dist_root/js/*.tgz
 
     log "Discovering local package names..."

From 79e6e12b4e29ce25bb5d33dbbc05d32953371036 Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Wed, 1 Apr 2020 01:05:58 +0300
Subject: [PATCH 22/34] remove debug logs

---
 packages/aws-cdk/test/integ/run-against-dist.bash | 2 --
 1 file changed, 2 deletions(-)

diff --git a/packages/aws-cdk/test/integ/run-against-dist.bash b/packages/aws-cdk/test/integ/run-against-dist.bash
index af7e98412a8fe..749414bc9908e 100644
--- a/packages/aws-cdk/test/integ/run-against-dist.bash
+++ b/packages/aws-cdk/test/integ/run-against-dist.bash
@@ -95,8 +95,6 @@ function serve_npm_packages() {
 
   use_verdaccio
 
-  echo "tarballs = ${tarballs}"
-
   log "Publishing NPM tarballs..."
   for tgz in $tarballs; do
     # Doesn't matter what directory it is, just shouldn't be the

From 1588905d2ef0bc8bfddc21f76647013903e37b19 Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Wed, 1 Apr 2020 01:09:10 +0300
Subject: [PATCH 23/34] some logs

---
 packages/aws-cdk/test/integ/run-wrappers/repo/npm | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/aws-cdk/test/integ/run-wrappers/repo/npm b/packages/aws-cdk/test/integ/run-wrappers/repo/npm
index aa2b8ca90ce37..097f6ff107fdb 100755
--- a/packages/aws-cdk/test/integ/run-wrappers/repo/npm
+++ b/packages/aws-cdk/test/integ/run-wrappers/repo/npm
@@ -6,6 +6,8 @@ command=$1
 lerna=$REPO_ROOT/node_modules/.bin/lerna
 
 if [ ! -z ${USE_PUBLISHED_FRAMEWORK_VERSION:-} ]; then
+  # simply pass through to npm and install the published package.
+  echo "Running original NPM command since we are testing against published framework version"
   exec $ORIGINAL_NPM "$@"
 elif [[ "$command" == "install" || "$command" == "i" ]]; then
   npmargs="install"

From 2c681e9d47b711e40c7e200e4018cee5ce59f152 Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Wed, 1 Apr 2020 01:15:44 +0300
Subject: [PATCH 24/34] added regression tests work directories to ignore

---
 packages/aws-cdk/.gitignore | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/packages/aws-cdk/.gitignore b/packages/aws-cdk/.gitignore
index 96d158bce819f..d47d255062905 100644
--- a/packages/aws-cdk/.gitignore
+++ b/packages/aws-cdk/.gitignore
@@ -17,3 +17,7 @@ nyc.config.js
 
 !test/integ/run-wrappers/dist
 !test/integ/cli/**/*
+
+# Might be created when running regression tests.
+# But normally should be deleted after execution.
+test/integ/cli-backwards-tests-*
\ No newline at end of file

From 9c630766537a47309aaaf97039c943727c15b101 Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Wed, 1 Apr 2020 01:19:41 +0300
Subject: [PATCH 25/34] added regression tests instructions in CLI contrib
 guide

---
 packages/aws-cdk/CONTRIBUTING.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/packages/aws-cdk/CONTRIBUTING.md b/packages/aws-cdk/CONTRIBUTING.md
index d1f98e709a1a2..5da08da820643 100644
--- a/packages/aws-cdk/CONTRIBUTING.md
+++ b/packages/aws-cdk/CONTRIBUTING.md
@@ -19,6 +19,17 @@ Run:
 npm run integ-cli
 ```
 
+In addition, you can run CLI integration compatibility tests. 
+These run integration tests of the previously published version. 
+They make sure you don't introduce changes that break any existing functionality.
+
+Run:
+
+```
+npm run integ-cli-backwards # run against latest CLI and Framework.
+npm run integ-cli-framework # run against latest CLI and previous Framework.
+```
+
 ### Init template integration tests
 
 Init template tests will initialize and compile the init templates that the

From 60f816b4d38e74d214291dd50fdf8e42285c97e4 Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Thu, 2 Apr 2020 18:46:56 +0300
Subject: [PATCH 26/34] added comments about why STACK_NAME_PREFIX is needed in
 the SNS topic names

---
 .../integ/cli/test-cdk-deploy-nested-stack-with-parameters.sh   | 2 ++
 .../test/integ/cli/test-cdk-deploy-wildcard-with-parameters.sh  | 2 ++
 .../aws-cdk/test/integ/cli/test-cdk-deploy-with-parameters.sh   | 2 ++
 3 files changed, 6 insertions(+)

diff --git a/packages/aws-cdk/test/integ/cli/test-cdk-deploy-nested-stack-with-parameters.sh b/packages/aws-cdk/test/integ/cli/test-cdk-deploy-nested-stack-with-parameters.sh
index e2c14d47520f9..b2389899ee71b 100755
--- a/packages/aws-cdk/test/integ/cli/test-cdk-deploy-nested-stack-with-parameters.sh
+++ b/packages/aws-cdk/test/integ/cli/test-cdk-deploy-nested-stack-with-parameters.sh
@@ -6,6 +6,8 @@ source ${scriptdir}/common.bash
 
 setup
 
+# STACK_NAME_PREFIX is used in MyTopicParam to allow multiple instances
+# of this test to run in parallel, othewise they will attempt to create the same SNS topic.
 stack_arn=$(cdk deploy -v ${STACK_NAME_PREFIX}-with-nested-stack-using-parameters --parameters "MyTopicParam=${STACK_NAME_PREFIX}ThereIsNoSpoon")
 echo "Stack deployed successfully"
 
diff --git a/packages/aws-cdk/test/integ/cli/test-cdk-deploy-wildcard-with-parameters.sh b/packages/aws-cdk/test/integ/cli/test-cdk-deploy-wildcard-with-parameters.sh
index ed75c4c195f77..30585a0ca530d 100755
--- a/packages/aws-cdk/test/integ/cli/test-cdk-deploy-wildcard-with-parameters.sh
+++ b/packages/aws-cdk/test/integ/cli/test-cdk-deploy-wildcard-with-parameters.sh
@@ -6,6 +6,8 @@ source ${scriptdir}/common.bash
 
 setup
 
+# STACK_NAME_PREFIX is used in OtherTopicNameParam to allow multiple instances
+# of this test to run in parallel, othewise they will attempt to create the same SNS topic.
 stack_arns=$(cdk deploy ${STACK_NAME_PREFIX}-param-test-\* --parameters "${STACK_NAME_PREFIX}-param-test-1:TopicNameParam=${STACK_NAME_PREFIX}bazinga" --parameters "${STACK_NAME_PREFIX}-param-test-2:OtherTopicNameParam=${STACK_NAME_PREFIX}ThatsMySpot")
 echo "Stack deployed successfully"
 
diff --git a/packages/aws-cdk/test/integ/cli/test-cdk-deploy-with-parameters.sh b/packages/aws-cdk/test/integ/cli/test-cdk-deploy-with-parameters.sh
index 9e162faac2a61..a0abe0ddaee9a 100755
--- a/packages/aws-cdk/test/integ/cli/test-cdk-deploy-with-parameters.sh
+++ b/packages/aws-cdk/test/integ/cli/test-cdk-deploy-with-parameters.sh
@@ -6,6 +6,8 @@ source ${scriptdir}/common.bash
 
 setup
 
+# STACK_NAME_PREFIX is used in TopicNameParam to allow multiple instances
+# of this test to run in parallel, othewise they will attempt to create the same SNS topic.
 stack_arn=$(cdk deploy -v ${STACK_NAME_PREFIX}-param-test-1 --parameters "TopicNameParam=${STACK_NAME_PREFIX}bazinga")
 echo "Stack deployed successfully"
 

From 001120551e196c38c18eb4db02a59137b58fcbac Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Thu, 2 Apr 2020 19:47:07 +0300
Subject: [PATCH 27/34] rename some scripts and more detailed explanation in
 contrib guide

---
 packages/aws-cdk/CONTRIBUTING.md              | 37 +++++++++++++++----
 packages/aws-cdk/package.json                 |  6 +--
 .../scripts/integ-cli-no-regression.sh        | 10 +++++
 .../aws-cdk/scripts/integ-cli-regression.sh   | 14 +++++++
 packages/aws-cdk/scripts/integ-cli.sh         | 10 +++++
 packages/aws-cdk/test/integ/cli/test.sh       |  2 +-
 .../aws-cdk/test/integ/test-cli-framework.sh  |  4 --
 ...st-cli-regression-against-current-code.sh} |  0
 ...t-cli-regression-against-latest-release.sh |  4 ++
 9 files changed, 72 insertions(+), 15 deletions(-)
 create mode 100755 packages/aws-cdk/scripts/integ-cli-no-regression.sh
 create mode 100644 packages/aws-cdk/scripts/integ-cli-regression.sh
 create mode 100644 packages/aws-cdk/scripts/integ-cli.sh
 delete mode 100755 packages/aws-cdk/test/integ/test-cli-framework.sh
 rename packages/aws-cdk/test/integ/{test-cli-backwards.sh => test-cli-regression-against-current-code.sh} (100%)
 create mode 100755 packages/aws-cdk/test/integ/test-cli-regression-against-latest-release.sh

diff --git a/packages/aws-cdk/CONTRIBUTING.md b/packages/aws-cdk/CONTRIBUTING.md
index 5da08da820643..09ab973fa95f2 100644
--- a/packages/aws-cdk/CONTRIBUTING.md
+++ b/packages/aws-cdk/CONTRIBUTING.md
@@ -16,18 +16,41 @@ REQUIREMENTS
 Run:
 
 ```
-npm run integ-cli
+yarn integ-cli
 ```
 
-In addition, you can run CLI integration compatibility tests. 
-These run integration tests of the previously published version. 
-They make sure you don't introduce changes that break any existing functionality.
+There are two types of tests involved in the integration suite:
 
-Run:
+#### Functional
+
+These tests simply run the local integration tests located in [`test/integ/cli`](./test/integ/cli). They test the proper deployment of stacks and in general the correctness of the actions performed by the CLI.
+
+You can run these specifically by executing:
 
+```console
+yarn integ-cli-no-regression
 ```
-npm run integ-cli-backwards # run against latest CLI and Framework.
-npm run integ-cli-framework # run against latest CLI and previous Framework.
+
+#### Regression
+
+Validate that previously tested functionality still works in light of recent changes to the CLI. This is done by fetching the functional tests of the latest published release, and running them against the new CLI code.
+
+These tests run in two variations:
+
+- **against local framework code**
+
+  Use your local framework code. This is important to make sure the new CLI version
+  will work properly with the new framework version. 
+
+- **against latest release code**
+
+  Fetches the framework code from the latest release. This is important to make sure
+  the new CLI version does not rely on new framework features to provide the same functionality.
+
+You can run these specifically by executing:
+
+```console
+yarn integ-cli-regression
 ```
 
 ### Init template integration tests
diff --git a/packages/aws-cdk/package.json b/packages/aws-cdk/package.json
index 5e620fae95c0f..097169ab9bb24 100644
--- a/packages/aws-cdk/package.json
+++ b/packages/aws-cdk/package.json
@@ -17,9 +17,9 @@
     "package": "cdk-package",
     "build+test+package": "npm run build+test && npm run package",
     "build+test": "npm run build && npm test",
-    "integ-cli": "test/integ/run-against-repo test/integ/cli/test.sh",
-    "integ-cli-backwards": "test/integ/run-against-repo test/integ/test-cli-backwards.sh",
-    "integ-cli-framework": "test/integ/run-against-repo test/integ/test-cli-framework.sh",
+    "integ-cli": "scripts/integ-cli.sh",
+    "integ-cli-regression": "scripts/integ-cli-regression.sh",
+    "integ-cli-no-regression": "scripts/integ-cli-no-regression.sh",
     "integ-init": "test/integ/run-against-dist test/integ/init/test-all.sh"
   },
   "cdk-build": {
diff --git a/packages/aws-cdk/scripts/integ-cli-no-regression.sh b/packages/aws-cdk/scripts/integ-cli-no-regression.sh
new file mode 100755
index 0000000000000..f8ffea80888f7
--- /dev/null
+++ b/packages/aws-cdk/scripts/integ-cli-no-regression.sh
@@ -0,0 +1,10 @@
+#!/bin/bash
+# 
+# Run only local integration tests.
+#
+set -eu
+
+scriptdir=$(cd $(dirname $0) && pwd)
+
+echo "Running local integration tests"
+./test/integ/run-against-repo test/integ/cli/test.sh
diff --git a/packages/aws-cdk/scripts/integ-cli-regression.sh b/packages/aws-cdk/scripts/integ-cli-regression.sh
new file mode 100644
index 0000000000000..e0925a7ab26c6
--- /dev/null
+++ b/packages/aws-cdk/scripts/integ-cli-regression.sh
@@ -0,0 +1,14 @@
+#!/bin/bash
+# 
+# Run only local integration tests.
+#
+set -eu
+
+scriptdir=$(cd $(dirname $0) && pwd)
+repo_root=$(realpath ${scriptdir}/..)
+
+echo "Running regression tests against local code"
+${repo_root}/test/integ/run-against-repo test-cli-regression-against-current-code.sh
+
+echo "Running regression tests against local CLI and published framework"
+${repo_root}/test/integ/run-against-repo test-cli-regression-against-latest-release.sh
\ No newline at end of file
diff --git a/packages/aws-cdk/scripts/integ-cli.sh b/packages/aws-cdk/scripts/integ-cli.sh
new file mode 100644
index 0000000000000..5307cf15336b7
--- /dev/null
+++ b/packages/aws-cdk/scripts/integ-cli.sh
@@ -0,0 +1,10 @@
+#!/bin/bash
+# 
+# Run both local integration tests and regression tests.
+#
+set -eu
+
+scriptdir=$(cd $(dirname $0) && pwd)
+
+${scriptdir}/integ-cli-no-regression.sh
+${scriptdir}/integ-cli-regression.sh
diff --git a/packages/aws-cdk/test/integ/cli/test.sh b/packages/aws-cdk/test/integ/cli/test.sh
index ecb0875fd10bc..86d11ba99bb8e 100755
--- a/packages/aws-cdk/test/integ/cli/test.sh
+++ b/packages/aws-cdk/test/integ/cli/test.sh
@@ -36,6 +36,6 @@ for test in $(cd ${scriptdir} && ls test-*.sh); do
 
   echo "${test}"
   echo "============================================================================================"
-  /bin/bash ${scriptdir}/${test}
+  # /bin/bash ${scriptdir}/${test}
 done
 
diff --git a/packages/aws-cdk/test/integ/test-cli-framework.sh b/packages/aws-cdk/test/integ/test-cli-framework.sh
deleted file mode 100755
index bb0e6dc9e8ad5..0000000000000
--- a/packages/aws-cdk/test/integ/test-cli-framework.sh
+++ /dev/null
@@ -1,4 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-integdir=$(cd $(dirname $0) && pwd)
-USE_PUBLISHED_FRAMEWORK_VERSION=True ${integdir}/test-cli-backwards.sh
diff --git a/packages/aws-cdk/test/integ/test-cli-backwards.sh b/packages/aws-cdk/test/integ/test-cli-regression-against-current-code.sh
similarity index 100%
rename from packages/aws-cdk/test/integ/test-cli-backwards.sh
rename to packages/aws-cdk/test/integ/test-cli-regression-against-current-code.sh
diff --git a/packages/aws-cdk/test/integ/test-cli-regression-against-latest-release.sh b/packages/aws-cdk/test/integ/test-cli-regression-against-latest-release.sh
new file mode 100755
index 0000000000000..0853db481ed32
--- /dev/null
+++ b/packages/aws-cdk/test/integ/test-cli-regression-against-latest-release.sh
@@ -0,0 +1,4 @@
+#!/bin/bash
+set -euo pipefail
+integdir=$(cd $(dirname $0) && pwd)
+USE_PUBLISHED_FRAMEWORK_VERSION=True ${integdir}/test-cli-regression-against-current-code.sh

From 2f7394c225b74f94407b8fe4f22546d383375244 Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Thu, 2 Apr 2020 21:01:43 +0300
Subject: [PATCH 28/34] fix path to scripts

---
 packages/aws-cdk/scripts/integ-cli-regression.sh | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
 mode change 100644 => 100755 packages/aws-cdk/scripts/integ-cli-regression.sh

diff --git a/packages/aws-cdk/scripts/integ-cli-regression.sh b/packages/aws-cdk/scripts/integ-cli-regression.sh
old mode 100644
new mode 100755
index e0925a7ab26c6..7b281264a637f
--- a/packages/aws-cdk/scripts/integ-cli-regression.sh
+++ b/packages/aws-cdk/scripts/integ-cli-regression.sh
@@ -8,7 +8,7 @@ scriptdir=$(cd $(dirname $0) && pwd)
 repo_root=$(realpath ${scriptdir}/..)
 
 echo "Running regression tests against local code"
-${repo_root}/test/integ/run-against-repo test-cli-regression-against-current-code.sh
+${repo_root}/test/integ/run-against-repo ${repo_root}/test/integ/test-cli-regression-against-current-code.sh
 
 echo "Running regression tests against local CLI and published framework"
-${repo_root}/test/integ/run-against-repo test-cli-regression-against-latest-release.sh
\ No newline at end of file
+${repo_root}/test/integ/run-against-repo ${repo_root}/test/integ/test-cli-regression-against-latest-release.sh
\ No newline at end of file

From a6d07fe5e04ab2882c51a182f1b56199dd77f832 Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Thu, 2 Apr 2020 21:10:51 +0300
Subject: [PATCH 29/34] some rephrasing

---
 packages/aws-cdk/CONTRIBUTING.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/aws-cdk/CONTRIBUTING.md b/packages/aws-cdk/CONTRIBUTING.md
index 09ab973fa95f2..34c2e43c0fc36 100644
--- a/packages/aws-cdk/CONTRIBUTING.md
+++ b/packages/aws-cdk/CONTRIBUTING.md
@@ -19,13 +19,13 @@ Run:
 yarn integ-cli
 ```
 
-There are two types of tests involved in the integration suite:
+This command runs two types of tests:
 
 #### Functional
 
 These tests simply run the local integration tests located in [`test/integ/cli`](./test/integ/cli). They test the proper deployment of stacks and in general the correctness of the actions performed by the CLI.
 
-You can run these specifically by executing:
+You can run also run just these tests by executing:
 
 ```console
 yarn integ-cli-no-regression
@@ -47,7 +47,7 @@ These tests run in two variations:
   Fetches the framework code from the latest release. This is important to make sure
   the new CLI version does not rely on new framework features to provide the same functionality.
 
-You can run these specifically by executing:
+You can run also run just these tests by executing:
 
 ```console
 yarn integ-cli-regression

From bda1dba1d25c12ffa4d4510856866b6953917402 Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Thu, 2 Apr 2020 21:14:25 +0300
Subject: [PATCH 30/34] typos

---
 packages/aws-cdk/CONTRIBUTING.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/aws-cdk/CONTRIBUTING.md b/packages/aws-cdk/CONTRIBUTING.md
index 34c2e43c0fc36..6ee9632a9ef93 100644
--- a/packages/aws-cdk/CONTRIBUTING.md
+++ b/packages/aws-cdk/CONTRIBUTING.md
@@ -25,7 +25,7 @@ This command runs two types of tests:
 
 These tests simply run the local integration tests located in [`test/integ/cli`](./test/integ/cli). They test the proper deployment of stacks and in general the correctness of the actions performed by the CLI.
 
-You can run also run just these tests by executing:
+You can also run just these tests by executing:
 
 ```console
 yarn integ-cli-no-regression
@@ -47,7 +47,7 @@ These tests run in two variations:
   Fetches the framework code from the latest release. This is important to make sure
   the new CLI version does not rely on new framework features to provide the same functionality.
 
-You can run also run just these tests by executing:
+You can also run just these tests by executing:
 
 ```console
 yarn integ-cli-regression

From 226b95f33aa6ea67593ec573ecaf1e37e013e81c Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Thu, 2 Apr 2020 21:15:51 +0300
Subject: [PATCH 31/34] typo

---
 packages/aws-cdk/test/integ/cli.exclusions.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/aws-cdk/test/integ/cli.exclusions.js b/packages/aws-cdk/test/integ/cli.exclusions.js
index f2fbd2fdb20e3..74726d645090e 100644
--- a/packages/aws-cdk/test/integ/cli.exclusions.js
+++ b/packages/aws-cdk/test/integ/cli.exclusions.js
@@ -2,7 +2,7 @@
 List of exclusions when running backwards compatibility tests.
 Add when you need to exclude a specific integration test from a specific version.
 
-This is an escape hatch for the rare cases where we need to intorduce
+This is an escape hatch for the rare cases where we need to introduce
 a change that breaks existing integration tests. (e.g security)
 
 For example:

From 714bd0e626ad4b8317348d354f48d33f60e74c0f Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Thu, 2 Apr 2020 21:17:39 +0300
Subject: [PATCH 32/34] quote env variable expansion in if statement

---
 packages/aws-cdk/test/integ/run-wrappers/repo/npm | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/aws-cdk/test/integ/run-wrappers/repo/npm b/packages/aws-cdk/test/integ/run-wrappers/repo/npm
index 097f6ff107fdb..e90e296bbef1d 100755
--- a/packages/aws-cdk/test/integ/run-wrappers/repo/npm
+++ b/packages/aws-cdk/test/integ/run-wrappers/repo/npm
@@ -5,7 +5,7 @@ command=$1
 
 lerna=$REPO_ROOT/node_modules/.bin/lerna
 
-if [ ! -z ${USE_PUBLISHED_FRAMEWORK_VERSION:-} ]; then
+if [ ! -z "${USE_PUBLISHED_FRAMEWORK_VERSION:-}" ]; then
   # simply pass through to npm and install the published package.
   echo "Running original NPM command since we are testing against published framework version"
   exec $ORIGINAL_NPM "$@"

From 786f61a7ea9d27585bc600ad543b02183ef80d06 Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Thu, 2 Apr 2020 22:53:14 +0300
Subject: [PATCH 33/34] added bunch of comments around the code

---
 packages/aws-cdk/test/integ/cli/test.sh               | 11 +++++++++++
 packages/aws-cdk/test/integ/run-against-dist.bash     |  2 +-
 .../integ/test-cli-regression-against-current-code.sh |  8 ++++++++
 3 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/packages/aws-cdk/test/integ/cli/test.sh b/packages/aws-cdk/test/integ/cli/test.sh
index 86d11ba99bb8e..0b977b2279623 100755
--- a/packages/aws-cdk/test/integ/cli/test.sh
+++ b/packages/aws-cdk/test/integ/cli/test.sh
@@ -9,13 +9,19 @@ prepare_fixture
 
 current_version=$(node -p "require('${scriptdir}/../../../package.json').version")
 
+# This allows injecting different versions, not just the current one.
+# Useful when testing.
 VERSION_UNDER_TEST=${VERSION_UNDER_TEST:-${current_version}}
 
+# check if a specific test should be skiped
+# from execution in the current version.
 function should_skip {
   test=$1
   echo $(node -p "require('${scriptdir}/../cli.exclusions.js').shouldSkip('${test}', '${VERSION_UNDER_TEST}')")
 }
 
+# get the justification for why a test is skipped.
+# this will fail if there is no justification!
 function get_skip_jusitification {
   test=$1
   echo $(node -p "require('${scriptdir}/../cli.exclusions.js').getJustification('${test}', '${VERSION_UNDER_TEST}')")
@@ -24,12 +30,17 @@ function get_skip_jusitification {
 for test in $(cd ${scriptdir} && ls test-*.sh); do
   echo "============================================================================================"
 
+  # first check this if this test should be skipped.
+  # this can happen when running in regression mode 
+  # when we introduce an intentional breaking change.
   skip=$(should_skip ${test})
 
   if [ ${skip} == "true" ]; then
 
+    # make sure we have a justification, this will fail if not.
     jusitification="$(get_skip_jusitification ${test})"
 
+    # skip this specific test.
     echo "${test} - skipped (${jusitification})"
     continue
   fi
diff --git a/packages/aws-cdk/test/integ/run-against-dist.bash b/packages/aws-cdk/test/integ/run-against-dist.bash
index 749414bc9908e..3e2253e145edf 100644
--- a/packages/aws-cdk/test/integ/run-against-dist.bash
+++ b/packages/aws-cdk/test/integ/run-against-dist.bash
@@ -22,7 +22,7 @@ function serve_npm_packages() {
     return
   fi
 
-  if [ ! -z ${USE_PUBLISHED_FRAMEWORK_VERSION:-} ]; then
+  if [ ! -z "${USE_PUBLISHED_FRAMEWORK_VERSION:-}" ]; then
 
     echo "Testing against latest published versions of the framework"
 
diff --git a/packages/aws-cdk/test/integ/test-cli-regression-against-current-code.sh b/packages/aws-cdk/test/integ/test-cli-regression-against-current-code.sh
index 8fd7113e686a7..940b044a8ed3a 100755
--- a/packages/aws-cdk/test/integ/test-cli-regression-against-current-code.sh
+++ b/packages/aws-cdk/test/integ/test-cli-regression-against-current-code.sh
@@ -1,4 +1,12 @@
 #!/bin/bash
+# 
+# Run our integration tests in regression mode against the 
+# local code of the framework and CLI.
+# 
+#   1. Download the latest released version of the aws-cdk repo.
+#   2. Copy its integration tests directory ((test/integ/cli)) here.
+#   3. Run the integration tests from the copied directory.
+#
 set -euo pipefail
 integdir=$(cd $(dirname $0) && pwd)
 

From 896c8666f4d042e951d69937e8b0aaef0ae6c5d2 Mon Sep 17 00:00:00 2001
From: epolon <epolon@amazon.com>
Date: Thu, 2 Apr 2020 23:10:13 +0300
Subject: [PATCH 34/34] more comments

---
 .../integ/test-cli-regression-against-current-code.sh | 11 +++++++++++
 .../test-cli-regression-against-latest-release.sh     |  4 ++++
 2 files changed, 15 insertions(+)

diff --git a/packages/aws-cdk/test/integ/test-cli-regression-against-current-code.sh b/packages/aws-cdk/test/integ/test-cli-regression-against-current-code.sh
index 940b044a8ed3a..25c7988b82ee2 100755
--- a/packages/aws-cdk/test/integ/test-cli-regression-against-current-code.sh
+++ b/packages/aws-cdk/test/integ/test-cli-regression-against-current-code.sh
@@ -17,8 +17,12 @@ function cleanup {
     rm -rf ${integ_under_test}
 }
 
+
 function get_latest_published_version {
 
+    # fetch the latest published version number.
+    # this is stored in the github releases under the 'latest' tag.
+
     github_headers=""
     if [[ "${GITHUB_TOKEN:-}" != "" ]]; then
         github_headers="Authorization: token ${GITHUB_TOKEN}"
@@ -33,6 +37,10 @@ function get_latest_published_version {
 
 function download_repo {
 
+    # we need to download the repo code from GitHub in order to extract
+    # the integration tests that were present in that version of the repo.
+    # TODO - consider switching this to 'npm install', 
+    # apparently we publish the integ tests in the package.    
     version=$1
 
     out="${temp_dir}/.repo.tar.gz"
@@ -43,6 +51,9 @@ function download_repo {
 
 }
 
+# this allows injecting different versions to be treated as the baseline
+# of the regression. usually this would just be the latest published version,
+# but this can even be a branch name during development and testing.
 VERSION_UNDER_TEST=${VERSION_UNDER_TEST:-$(get_latest_published_version)}
 
 trap cleanup INT EXIT
diff --git a/packages/aws-cdk/test/integ/test-cli-regression-against-latest-release.sh b/packages/aws-cdk/test/integ/test-cli-regression-against-latest-release.sh
index 0853db481ed32..fc3e4e3b9a859 100755
--- a/packages/aws-cdk/test/integ/test-cli-regression-against-latest-release.sh
+++ b/packages/aws-cdk/test/integ/test-cli-regression-against-latest-release.sh
@@ -1,4 +1,8 @@
 #!/bin/bash
 set -euo pipefail
 integdir=$(cd $(dirname $0) && pwd)
+
+# run the regular regression test but pass the env variable that will
+# eventually instruct our runners and wrappers to install the framework
+# from npmjs.org rather then using the local code.
 USE_PUBLISHED_FRAMEWORK_VERSION=True ${integdir}/test-cli-regression-against-current-code.sh