chore: add readme for cloud-assembly-schema #31151
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This points users to the correct repo for the source code. The contents of this README will be automatically updated to the contents of the README in the source code on every version update.
aws-cdk-automation
added
the
pr/needs-maintainer-review
evzzk
reviewed
Aug 21, 2024
|
|
||
| ## Versioning | ||
|
|
||
| The schema version is specified my the major version of the package release. It follows semantic versioning, but with a small twist. |
There was a problem hiding this comment.
Suggested change
| The schema version is specified my the major version of the package release. It follows semantic versioning, but with a small twist. | |
| The schema version is specified by the major version of the package release. It follows semantic versioning, but with a slight modification. |
evzzk
reviewed
Aug 21, 2024
comcalvi
approved these changes
Aug 21, 2024
| [`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 |
There was a problem hiding this comment.
Suggested change
| Its essentially a set of files and directories, one of which is the `manifest.json` file. It defines the set of instructions that are | |
| It contains the files the CDK CLI needs to deploy your application, including assets and the CloudFormation Template that defines your application's infrastructure. This includes `manifest.json`, which defines the instructions the CDK CLI follows to deploy your application. |
| > - 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. |
There was a problem hiding this comment.
Suggested change
| between the assembly and its consumers, we treat the manifest file as a well defined, versioned schema. | |
| between the assembly and its consumers, the manifest file follows a well defined, versioned schema. |
|
|
||
| ## Versioning | ||
|
|
||
| The schema version is specified my the major version of the package release. It follows semantic versioning, but with a small twist. |
There was a problem hiding this comment.
Suggested change
| The schema version is specified my the major version of the package release. It follows semantic versioning, but with a small twist. | |
| The schema version is specified by the major version of the package release. It follows semantic versioning, but with a small twist. |
Comment on lines
+32
to
+37
| 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. |
There was a problem hiding this comment.
Suggested change
| 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. | |
| Cloud assembly consumers must support every instruction in the cloud assembly manifest. Thus every change to the schema, breaking or not, is considered a `major` version bump. Changes that do not impact the schema are considered a `minor` version bump. |
Comment on lines
+40
to
+46
|
|
||
| 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. |
There was a problem hiding this comment.
Suggested change
| 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. | |
| If you'd like to consume the [schema file](./schema/cloud-assembly.schema.json) to validate the manifest, 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. |
|
Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork). |
aws-cdk-automation
removed
the
pr/needs-maintainer-review
AWS CodeBuild CI Report
Powered by github-codebuild-logs, available on the AWS Serverless Application Repository |
|
Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork). |
mergify
bot
deleted the
TheRealAmazonKendra/cloud-assembly-schema-readme
branch
|
Comments on closed issues and PRs are hard for our team to see. |
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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 #.
Reason for this change
Description of changes
Description of how you validated changes
Checklist
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license