Merge branch 'main' into merge-back/2.77.0

Author: iliapolo

CONTRIBUTING.md

@@ -332,6 +332,110 @@ $ cd packages/aws-cdk
 $ yarn watch & # runs in the background
 ```
 
+#### Verify your fix by deployment
+
+If your PR updates a specific library, you might want to write a simple CDK application and make sure it synthesizes and
+deploys correctly. For example, if you modify files under `packages/aws-cdk-lib/aws-eks`, you can write a simple CDK app in typescript to verify its behavior:
+
+
+```console
+$ cd packages/@aws-cdk-testing/framework-integ/test/aws-eks/test
+```
+
+Create a `sample.ts` like this:
+
+```ts
+import {
+  App, Stack,
+  aws_eks as eks,
+  aws_ec2 as ec2,
+} from 'aws-cdk-lib';
+import { getClusterVersionConfig } from './integ-tests-kubernetes-version';
+
+const app = new App();
+const env = { region: process.env.CDK_DEFAULT_REGION, account: process.env.CDK_DEFAULT_ACCOUNT };
+const stack = new Stack(app, 'my-test-stack', { env });
+
+const cluster = new eks.Cluster(stack, 'Cluster', {
+  vpc,
+  ...getClusterVersionConfig(stack),
+  defaultCapacity: 0,
+});
+```
+
+Run `yarn watch` or `npx tsc --watch` in a separate terminal to compile `sample.ts` to `sample.js`:
+
+```console
+$ cd packages/@aws-cdk-testing/framework-integ
+$ yarn watch
+or
+$ npx tsc --watch
+```
+
+Make sure you have configured [AWS CLI with AWS Authentication](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html#getting_started_auth) as we will deploy it in our AWS account.
+
+Deploy the sample app:
+
+```console
+$ cd packages/@aws-cdk-testing/framework-integ
+$ npx cdk -a test/aws-eks/test/sample.js diff
+$ npx cdk -a test/aws-eks/test/sample.js deploy
+```
+
+This allows you to iterate your development and ensure a minimal sample app would successfully deploy as you expect.
+You have the freedom to interact with it just as a common CDK app such as viewing differences with `npx cdk diff`
+or pass context variables with `npx cdk deploy -c`. You can rapidly iterate your testing with repeated deployments 
+by importing existing resource such as existing VPC. This can save a lot of time and help you focus on the core changes.
+
+```ts
+const vpc = ec2.Vpc.fromLookup(stack, 'Vpc', { isDefault: true });
+```
+
+As this is for testing only, do not commit `sample.ts` and `sample.js` to your PR branch.
+
+Alternatively, you can write this test as a new integration test like `integ.my-test.ts` and deploy it
+using `yarn integ --no-clean`. This may be useful when you need to publish a new 
+integration test:
+
+```console
+$ cd packages/@aws-cdk-testing/framework-integ
+$ yarn integ test/aws-eks/test/integ.my-test.js --no-clean --update-on-failed
+```
+
+After verifying your work with a simple deployment as above, you need to ensure your change can pass all existing
+unit tests and integ tests and fix them if necessary.
+
+Run all the unit tests for a specific module(e.g. aws-eks):
+
+```console
+$ cd packages/aws-cdk-lib
+$ yarn test aws-eks
+```
+
+Or run a specific unit test
+
+```console
+$ cd packages/aws-cdk-lib
+$ npx jest aws-eks/test/name.test.js
+```
+
+Run all integ tests for a specific module(e.g. aws-eks):
+
+```console
+$ cd packages/@aws-cdk-testing/framework-integ
+$ yarn integ --directory test/aws-eks/test
+```
+
+Or run a specific integ test:
+
+```console
+$ yarn integ --directory test/aws-eks/test/integ.name.js
+```
+
+See the [integration test guide](./INTEGRATION_TESTS.md) for a more complete guide on running
+CDK integration tests.
+
+
 ### Step 4: Pull Request
 
 * Create a commit with your changes and push them to a

buildspec-pr.yaml

@@ -2,6 +2,10 @@ version: 0.2
 
 # This buildspec is intended to be used by GitHub PR builds.
 
+env:
+  variables:
+    PR_BUILD: true
+
 phases:
   install:
     commands:

packages/@aws-cdk/cfnspec/build-tools/build.ts

@@ -6,16 +6,28 @@
  */
 
 import * as path from 'path';
+import * as fs from 'fs-extra';
 import * as md5 from 'md5';
 import { massageSpec, normalize } from './massage-spec';;
 import { writeSorted, applyPatchSet, applyAndWrite } from './patch-set';
+import { validateSpecificationEvolution } from './validate-evolution';
 import { schema } from '../lib';
 
 async function main() {
   const inputDir = path.join(process.cwd(), 'spec-source');
   const outDir = path.join(process.cwd(), 'spec');
 
-  await generateResourceSpecification(inputDir, path.join(outDir, 'specification.json'));
+  // If this is a PR build check the spec for evolution (this is set in buildspec-pr.yaml)
+  const outputFile = path.join(outDir, 'specification.json');
+  if (process.env.CODEBUILD_WEBHOOK_TRIGGER?.startsWith('pr/')) {
+    await validateSpecificationEvolution(async () => {
+      await generateResourceSpecification(inputDir, outputFile);
+      return fs.readJson(outputFile);
+    });
+  } else {
+    await generateResourceSpecification(inputDir, outputFile);
+  }
+
   await applyAndWrite(path.join(outDir, 'cfn-lint.json'), path.join(inputDir, 'cfn-lint'));
   await applyAndWrite(path.join(outDir, 'cfn-docs.json'), path.join(inputDir, 'cfn-docs'));
 }