Skip to content

Commit

Permalink
chore: add readme for cloud-assembly-schema (#31151)
Browse files Browse the repository at this point in the history
This points users to the correct repo for the source code. No other changes have yet been made to this README. The contents of this README will be automatically updated to the contents of the README in the source code on every version update.

This change also includes removal of a file that shouldn't have been committed (.jsii.tabl.json) and the revert of unintended changes to the jest config.

### Issue # (if applicable)

Closes #<issue number here>.

### Reason for this change



### Description of changes



### Description of how you validated changes



### Checklist
- [ ] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md)

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
  • Loading branch information
TheRealAmazonKendra committed Aug 21, 2024
1 parent bbb8885 commit 76e7af6
Show file tree
Hide file tree
Showing 3 changed files with 73 additions and 1 deletion.
Binary file removed packages/aws-cdk-lib/.jsii.tabl.json.gz
Binary file not shown.
55 changes: 55 additions & 0 deletions packages/aws-cdk-lib/cloud-assembly-schema/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# Cloud Assembly Schema

This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.

## Cloud Assembly

The _Cloud Assembly_ is the output of the synthesis operation. It is produced as part of the
[`cdk synth`](https://github.com/aws/aws-cdk/tree/main/packages/aws-cdk#cdk-synthesize)
command, or the [`app.synth()`](https://github.com/aws/aws-cdk/blob/main/packages/@aws-cdk/core/lib/app.ts#L135) method invocation.

Its essentially a set of files and directories, one of which is the `manifest.json` file. It defines the set of instructions that are
needed in order to deploy the assembly directory.

> For example, when `cdk deploy` is executed, the CLI reads this file and performs its instructions:
>
> - Build container images.
> - Upload assets.
> - Deploy CloudFormation templates.
Therefore, the assembly is how the CDK class library and CDK CLI (or any other consumer) communicate. To ensure compatibility
between the assembly and its consumers, we treat the manifest file as a well defined, versioned schema.

## Schema

This module contains the typescript structs that comprise the `manifest.json` file, as well as the
generated [_json-schema_](./schema/cloud-assembly.schema.json).

## Versioning

The schema version is specified my the major version of the package release. It follows semantic versioning, but with a small twist.

When we add instructions to the assembly, they are reflected in the manifest file and the _json-schema_ accordingly.
Every such instruction, is crucial for ensuring the correct deployment behavior. This means that to properly deploy a cloud assembly,
consumers must be aware of every such instruction modification.

For this reason, every change to the schema, even though it might not strictly break validation of the _json-schema_ format,
is considered `major` version bump. All changes that do not impact the schema are considered a `minor` version bump.

## How to consume

If you'd like to consume the [schema file](./schema/cloud-assembly.schema.json) in order to do validations on `manifest.json` files,
simply download it from this repo and run it against standard _json-schema_ validators, such as [jsonschema](https://www.npmjs.com/package/jsonschema).

Consumers must take into account the `major` version of the schema they are consuming. They should reject cloud assemblies
with a `major` version that is higher than what they expect. While schema validation might pass on such assemblies, the deployment integrity
cannot be guaranteed because some instructions will be ignored.

> For example, if your consumer was built when the schema version was 2.0.0, you should reject deploying cloud assemblies with a
> manifest version of 3.0.0.
## Contributing

The source code for this file has been moved to CDKLabs.

See [Contribution Guide](https://github.com/cdklabs/cloud-assembly-schema/blob/main/CONTRIBUTING.md)
19 changes: 18 additions & 1 deletion packages/aws-cdk-lib/jest.config.js
Original file line number Diff line number Diff line change
@@ -1 +1,18 @@
"use strict";const baseConfig=require("@aws-cdk/cdk-build-tools/config/jest.config");module.exports={...baseConfig,testMatch:["<rootDir>/**/test/**/?(*.)+(test).ts"],coverageThreshold:{global:{branches:35,statements:55}}};
const baseConfig = require('@aws-cdk/cdk-build-tools/config/jest.config');

/** @type {import('ts-jest').JestConfigWithTsJest} */
module.exports = {
...baseConfig,

// Different than usual
testMatch: [
'<rootDir>/**/test/**/?(*.)+(test).ts',
],

coverageThreshold: {
global: {
branches: 35,
statements: 55,
},
},
};

0 comments on commit 76e7af6

Please sign in to comment.