chore: "compat" script for api compatibility check (aws#4893)

* chore: "compat" script for api compatibility check

Add a `compat` script to all modules and to the repo root which runs api compatibility checks.
Also add a section in the contribution guide that explains about api checks.

Add a "build" and "pack" scripts in the root package.json so users can just run "yarn build/pack" from the root.

* cr tweaks

CONTRIBUTING.md

@@ -7,6 +7,7 @@ and let us know if it's not up-to-date (even better, submit a PR with your  corr
 
 - [Getting Started](#getting-started)
 - [Pull Requests](#pull-requests)
+  - [Pull Request Checklist](#pull-request-checklist)
   - [Step 1: Open Issue](#step-1-open-issue)
   - [Step 2: Design (optional)](#step-2-design-optional)
   - [Step 3: Work your Magic](#step-3-work-your-magic)
@@ -34,6 +35,7 @@ and let us know if it's not up-to-date (even better, submit a PR with your  corr
   - [Finding dependency cycles between packages](#finding-dependency-cycles-between-packages)
   - [Updating all Dependencies](#updating-all-dependencies)
   - [Running CLI integration tests](#running-cli-integration-tests)
+  - [API Compatibility Checks](#api-compatibility-checks)
 - [Troubleshooting](#troubleshooting)
 - [Debugging](#debugging)
   - [Connecting the VS Code Debugger](#connecting-the-vs-code-debugger)
@@ -47,7 +49,7 @@ with [Yarn >= 1.19.1](https://yarnpkg.com/lang/en/docs/install) should be suffic
 ```console
 $ git clone https://github.com/aws/aws-cdk.git
 $ cd aws-cdk
-$ ./build.sh
+$ yarn build
 ```
 
 If you wish to produce language bindings through `pack.sh`, you will need the following toolchains
@@ -191,10 +193,10 @@ fixed for you by hitting `Ctrl-.` when your cursor is on a red underline.
 
 ### Main build scripts
 
-The build process is divided into stages, so you can invoke them as needed:
+The build process is divided into stages, so you can invoke them as needed from the root of the repo:
 
-- __`build.sh`__: runs `yarn build` and `yarn test` in all modules (in topological order).
-- __`pack.sh`__: packages all modules to all supported languages and produces a `dist/` directory with all the outputs
+- __`yarn build`__: runs the `build` and `test` commands in all modules (in topological order).
+- __`yarn pack`__: packages all modules to all supported languages and produces a `dist/` directory with all the outputs
   (running this script requires that you installed the [toolchains](#Toolchains) for all target languages on your
   system).
 
@@ -327,7 +329,7 @@ Install and build:
 
 ```console
 $ ./install.sh
-$ ./build.sh
+$ yarn build
 ```
 
 If you also wish to package to all languages, make sure you have all the [toolchains](#Toolchains) and now run:
@@ -479,13 +481,46 @@ run as part of the regular build, since they have some particular requirements.
 See the [CLI CONTRIBUTING.md file](packages/aws-cdk/CONTRIBUTING.md) for
 more information on running those tests.
 
+### API Compatibility Checks
+
+All stable APIs in the CDK go through a compatibility check during build using
+the [jsii-diff] tool. This tool downloads the latest released version from npm
+and verifies that the APIs in the current build have not changed in a breaking
+way.
+
+[jsii-diff]: https://www.npmjs.com/package/jsii-diff
+
+Compatibility checks always run as part of a full build (`yarn build`).
+
+You can use `yarn compat` to run compatibility checks for all modules:
+
+```shell
+(working directory is repo root)
+$ yarn build
+$ yarn compat
+```
+
+You can also run `compat` from individual package directories:
+
+```shell
+$ cd packages/@aws-cdk/aws-sns
+$ yarn build
+$ yarn compat
+```
+
+The only case where it is legitimate to break a public API is if the existing
+API is a bug that blocked the usage of a feature. This means that by breaking
+this API we will not break anyone, because they weren't able to use it. The file
+`allowed-breaking-changes.txt` in the root of the repo is an exclusion file that
+can be used in these cases.
+
 ## Troubleshooting
 
 Most build issues can be solved by doing a full clean rebuild:
 
 ```shell
 $ git clean -fqdx .
-$ ./build.sh
+$ yarn build
 ```
 
 However, this will be time consuming. In this section we'll describe some common issues you may encounter and some more

package.json

@@ -7,6 +7,9 @@
   },
   "scripts": {
     "pkglint": "lerna --scope pkglint run build && lerna run pkglint",
+    "build": "./build.sh",
+    "pack": "./pack.sh",
+    "compat": "./scripts/check-api-compatibility.sh",
     "build-all": "tsc -b"
   },
   "devDependencies": {

packages/@aws-cdk/alexa-ask/package.json

@@ -46,7 +46,8 @@
     "awslint": "cdk-awslint",
     "cfn2ts": "cfn2ts",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "cdk-build": {
     "cloudformation": "Alexa::ASK"

packages/@aws-cdk/app-delivery/package.json

@@ -38,7 +38,8 @@
     "integ": "cdk-integ",
     "awslint": "cdk-awslint",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "dependencies": {
     "@aws-cdk/aws-cloudformation": "1.15.0",

packages/@aws-cdk/assets/package.json

@@ -44,7 +44,8 @@
     "package": "cdk-package",
     "awslint": "cdk-awslint",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "cdk-build": {
     "pre": [

packages/@aws-cdk/aws-amazonmq/package.json

@@ -46,7 +46,8 @@
     "awslint": "cdk-awslint",
     "cfn2ts": "cfn2ts",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "cdk-build": {
     "cloudformation": "AWS::AmazonMQ"

packages/@aws-cdk/aws-amplify/package.json

@@ -46,7 +46,8 @@
     "watch": "cdk-watch",
     "cfn2ts": "cfn2ts",
     "build+test": "npm run build && npm test",
-    "build+test+package": "npm run build+test && npm run package"
+    "build+test+package": "npm run build+test && npm run package",
+    "compat": "cdk-compat"
   },
   "cdk-build": {
     "cloudformation": "AWS::Amplify"

packages/@aws-cdk/aws-apigateway/package.json

@@ -45,7 +45,8 @@
     "awslint": "cdk-awslint",
     "cfn2ts": "cfn2ts",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "cdk-build": {
     "cloudformation": [

packages/@aws-cdk/aws-applicationautoscaling/package.json

@@ -45,7 +45,8 @@
     "awslint": "cdk-awslint",
     "cfn2ts": "cfn2ts",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "cdk-build": {
     "cloudformation": "AWS::ApplicationAutoScaling"

packages/@aws-cdk/aws-appmesh/package.json

@@ -46,7 +46,8 @@
     "watch": "cdk-watch",
     "cfn2ts": "cfn2ts",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "cdk-build": {
     "cloudformation": "AWS::AppMesh"

packages/@aws-cdk/aws-appstream/package.json

@@ -46,7 +46,8 @@
     "awslint": "cdk-awslint",
     "cfn2ts": "cfn2ts",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "cdk-build": {
     "cloudformation": "AWS::AppStream"

packages/@aws-cdk/aws-appsync/package.json

@@ -45,7 +45,8 @@
     "awslint": "cdk-awslint",
     "cfn2ts": "cfn2ts",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "cdk-build": {
     "cloudformation": "AWS::AppSync"

packages/@aws-cdk/aws-athena/package.json

@@ -48,7 +48,8 @@
     "awslint": "cdk-awslint",
     "cfn2ts": "cfn2ts",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "keywords": [
     "aws",

packages/@aws-cdk/aws-autoscaling-common/package.json

@@ -44,7 +44,8 @@
     "package": "cdk-package",
     "awslint": "cdk-awslint",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "keywords": [
     "aws",

packages/@aws-cdk/aws-autoscaling-hooktargets/package.json

@@ -45,7 +45,8 @@
     "awslint": "cdk-awslint",
     "cfn2ts": "cfn2ts",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "keywords": [
     "aws",

packages/@aws-cdk/aws-autoscaling/package.json

@@ -45,7 +45,8 @@
     "awslint": "cdk-awslint",
     "cfn2ts": "cfn2ts",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "cdk-build": {
     "cloudformation": "AWS::AutoScaling"

packages/@aws-cdk/aws-autoscalingplans/package.json

@@ -45,7 +45,8 @@
     "awslint": "cdk-awslint",
     "cfn2ts": "cfn2ts",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "cdk-build": {
     "cloudformation": "AWS::AutoScalingPlans"

packages/@aws-cdk/aws-backup/package.json

@@ -46,7 +46,8 @@
     "watch": "cdk-watch",
     "cfn2ts": "cfn2ts",
     "build+test": "npm run build && npm test",
-    "build+test+package": "npm run build+test && npm run package"
+    "build+test+package": "npm run build+test && npm run package",
+    "compat": "cdk-compat"
   },
   "cdk-build": {
     "cloudformation": "AWS::Backup"

packages/@aws-cdk/aws-batch/package.json

@@ -45,7 +45,8 @@
     "awslint": "cdk-awslint",
     "cfn2ts": "cfn2ts",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "cdk-build": {
     "cloudformation": "AWS::Batch"

packages/@aws-cdk/aws-budgets/package.json

@@ -45,7 +45,8 @@
     "awslint": "cdk-awslint",
     "cfn2ts": "cfn2ts",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "cdk-build": {
     "cloudformation": "AWS::Budgets"

packages/@aws-cdk/aws-certificatemanager/package.json

@@ -45,7 +45,8 @@
     "awslint": "cdk-awslint",
     "cfn2ts": "cfn2ts",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "cdk-build": {
     "cloudformation": "AWS::CertificateManager"

packages/@aws-cdk/aws-cloud9/package.json

@@ -45,7 +45,8 @@
     "awslint": "cdk-awslint",
     "cfn2ts": "cfn2ts",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "cdk-build": {
     "cloudformation": "AWS::Cloud9"

packages/@aws-cdk/aws-cloudformation/package.json

@@ -45,7 +45,8 @@
     "awslint": "cdk-awslint",
     "cfn2ts": "cfn2ts",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "cdk-build": {
     "cloudformation": "AWS::CloudFormation"

packages/@aws-cdk/aws-cloudfront/package.json

@@ -45,7 +45,8 @@
     "awslint": "cdk-awslint",
     "cfn2ts": "cfn2ts",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "cdk-build": {
     "cloudformation": "AWS::CloudFront"

packages/@aws-cdk/aws-cloudtrail/package.json

@@ -45,7 +45,8 @@
     "cfn2ts": "cfn2ts",
     "integ": "cdk-integ",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "cdk-build": {
     "cloudformation": "AWS::CloudTrail"

packages/@aws-cdk/aws-cloudwatch-actions/package.json

@@ -45,7 +45,8 @@
     "awslint": "cdk-awslint",
     "cfn2ts": "cfn2ts",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "keywords": [
     "aws",

packages/@aws-cdk/aws-cloudwatch/package.json

@@ -45,7 +45,8 @@
     "awslint": "cdk-awslint",
     "cfn2ts": "cfn2ts",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "cdk-build": {
     "cloudformation": "AWS::CloudWatch"

packages/@aws-cdk/aws-codebuild/package.json

@@ -45,7 +45,8 @@
     "awslint": "cdk-awslint",
     "cfn2ts": "cfn2ts",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "cdk-build": {
     "cloudformation": "AWS::CodeBuild"

packages/@aws-cdk/aws-codecommit/package.json

@@ -45,7 +45,8 @@
     "awslint": "cdk-awslint",
     "cfn2ts": "cfn2ts",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "cdk-build": {
     "cloudformation": "AWS::CodeCommit"

packages/@aws-cdk/aws-codedeploy/package.json

@@ -45,7 +45,8 @@
     "awslint": "cdk-awslint",
     "cfn2ts": "cfn2ts",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "cdk-build": {
     "cloudformation": "AWS::CodeDeploy"

packages/@aws-cdk/aws-codepipeline-actions/package.json

@@ -44,7 +44,8 @@
     "package": "cdk-package",
     "awslint": "cdk-awslint",
     "build+test+package": "npm run build+test && npm run package",
-    "build+test": "npm run build && npm test"
+    "build+test": "npm run build && npm test",
+    "compat": "cdk-compat"
   },
   "nyc": {
     "statements": 70