rfc: tree.json #4053

shivlaks · 2019-09-13T00:24:15Z

Strategy for publishing the construct tree which represents a CDK app as a part of the Cloud Assembly that the CDK generates.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

mergify · 2019-09-13T00:24:54Z

Thanks so much for taking the time to contribute to the AWS CDK ❤️

We will shortly assign someone to review this pull request and help get it
merged. In the meantime, please take a minute to make sure you follow this
checklist:

PR title type(scope): text
- type: fix, feat, refactor go into CHANGELOG, chore is hidden
- scope: name of module without aws- or cdk- prefix or postfix (e.g. s3 instead of aws-s3-deployment)
- text: use all lower-case, do not end with a period, do not include issue refs
PR Description
- Rationale: describe rationale of change and approach taken
- Issues: indicate issues fixed via: fixes #xxx or closes #xxx
- Breaking?: last paragraph: BREAKING CHANGE: <describe what changed + link for details>
Testing
- Unit test added. Prefer to add a new test rather than modify existing tests
- CLI or init templates change? Re-run/add CLI integration tests
Documentation
- README: update module README to describe new features
- API docs: public APIs must be documented. Copy from official AWS docs when possible
- Design: for significant features, follow design process

ghost

This looks solid. Clear and concise and describes the benefits well.

design/construct-tree.md

eladb

See comments

nija-at · 2019-09-17T10:08:45Z

design/construct-tree.md

+    3. ***Metadata -*** Constructs will expose metadata which will include an array of objects associated with the construct.
+        1. **Location** - The full path of the location where the construct is defined. This will support use cases where the construct-tree nodes can support navigability back to the declaration in the IDE itself.
+        2. ***Properties*** - Constructs will opt into the set of properties, and these will be exposed. Higher level constructs (L2 and L3) will expose properties and values of the resources they contain and not necessarily enumerate every property that’s available for a resource. This will especially be useful for constructs that are opinionated and set defaults on behalf of developers. Low level constructs (L1) will expose all properties that are configured.
+        3. ***Errors/Warnings*** - Errors and warnings that are produced during synthesis indicating validation failures, deprecation notices, guidance, etc will be included in the tree. These are emitted at the construct level although the message may point towards a specific property. The construct tree should be complete and include validation failures for all resources in the CDK application rather than just just fail on the first error.


Do errors & warnings fall under "minimal set of requirements"?

nija-at · 2019-09-17T10:14:26Z

design/construct-tree.md

+2. **Constructs**
+    1. ***Nodes*** - CDK application constructs at the root and drill down to the constructs it contains (1+ cloud resources.) Initially, we will focus our attention on AWS resources, but the model is extensible to cloud components from any provider
+    2. **Types/Hierarchy** - Types and hierarchy information will contain the details around the level of abstraction (L1, L2, L3..), service(s), and resource(s) that they represent.
+    3. ***Metadata -*** Constructs will expose metadata which will include an array of objects associated with the construct.


The 'Metadata' group sounds vague and it's not clear why these 3 fall under this but not 'Type'.

I'd suggest dropping this grouping in this requirements section altogether. Perhaps something along the lines of -
"The following information will be exposed for all instances of all CDK constructs, involved in the application. They are (a) Type & hierarchy - ... (b) source location - .... (c) ..."

Would that be better?

design/construct-tree.md

nija-at · 2019-09-17T10:46:48Z

design/construct-tree.md

+1. **Format** - Publish underlying data as a `.json` file that contains the information required to render a construct tree view. The construct tree illustrated in the previous section is only a depiction of what a human readable(ish) view might look like
+2. **Constructs**
+    1. ***Nodes*** - CDK application constructs at the root and drill down to the constructs it contains (1+ cloud resources.) Initially, we will focus our attention on AWS resources, but the model is extensible to cloud components from any provider
+    2. **Types/Hierarchy** - Types and hierarchy information will contain the details around the level of abstraction (L1, L2, L3..), service(s), and resource(s) that they represent.


I'm not sure I follow this.

Type - Is this the Type of the construct within CDK, or the type of resource (in the case of an L1) this renders into. Which one do we want? I suppose both.

What's hierarchy? And what exactly do we want to expose? From what I understand, there are two things here - one is the hierarchy of CDK Construct classes (viz. SingletonLambda → FunctionBase → IFunction) and the other is the hierarchy of how a specific (AWS) Resource got created. They're both valuable to power different experiences.

design/construct-tree.md

nija-at · 2019-09-17T10:52:17Z

design/construct-tree.md

+|---    |---    |---    |---  |
+|sourceLocation    |string    |Required    |location in source code where the construct is defined    |
+|resourceType |string |Required |type of resource (schema / classification terminology TBD) |
+|description    |string |Not Required |description of the construct |


+1 and why is it needed?

design/construct-tree.md

Publish the CDK construct hierarchy with the construct id and path to the cloud assembly directory, with a corresponding manifest entry. Motivation and proposal documented in RFC - #4053. This change focuses on integrating generating the metadata into the cloud assembly as part of the the 'synthesize' lifecycle phase. Subsequent changes will enrich the metadata file with additional information from the construct tree (see RFC).

Publish the CDK construct tree with the construct id and path to the cloud assembly directory, with a corresponding manifest entry. Motivation and proposal documented in RFC - #4053. This change focuses on integrating generating the metadata into the cloud assembly as part of the the 'synthesize' lifecycle phase. Subsequent changes will enrich the output with additional information about each construct (see RFC).

aws-cdk-automation · 2019-10-01T04:45:36Z

AWS CodeBuild CI Report

Result: FAILED
Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

…ceholders to describe source of construct properties

…rs to fill in source of metadata

… columns for construct properties

aws-cdk-automation · 2019-10-17T10:45:17Z

AWS CodeBuild CI Report

Result: FAILED
Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

aws-cdk-automation · 2019-10-17T10:51:55Z

AWS CodeBuild CI Report

Result: FAILED
Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

…and properties by naming convention

aws-cdk-automation · 2019-11-05T09:01:18Z

AWS CodeBuild CI Report

Result: FAILED
Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

mergify · 2019-12-16T12:34:52Z

Thanks so much for taking the time to contribute to the AWS CDK ❤️

We will shortly assign someone to review this pull request and help get it
merged. In the meantime, please take a minute to make sure you follow this
checklist:

PR title type(scope): text
- type: fix, feat, refactor go into CHANGELOG, chore is hidden
- scope: name of module without aws- or cdk- prefix or postfix (e.g. s3 instead of aws-s3-deployment)
- text: use all lower-case, do not end with a period, do not include issue refs
PR Description
- Rationale: describe rationale of change and approach taken
- Issues: indicate issues fixed via: fixes #xxx or closes #xxx
- Breaking?: last paragraph: BREAKING CHANGE: <describe what changed + link for details>
Testing
- Unit test added. Prefer to add a new test rather than modify existing tests
- CLI or init templates change? Re-run/add CLI integration tests
Documentation
- README: update module README to describe new features
- API docs: public APIs must be documented. Copy from official AWS docs when possible
- Design: for significant features, follow design process

mergify · 2019-12-16T13:01:38Z

Thanks so much for taking the time to contribute to the AWS CDK ❤️

We will shortly assign someone to review this pull request and help get it
merged. In the meantime, please take a minute to make sure you follow this
checklist:

PR title type(scope): text
- type: fix, feat, refactor go into CHANGELOG, chore is hidden
- scope: name of module without aws- or cdk- prefix or postfix (e.g. s3 instead of aws-s3-deployment)
- text: use all lower-case, do not end with a period, do not include issue refs
PR Description
- Rationale: describe rationale of change and approach taken
- Issues: indicate issues fixed via: fixes #xxx or closes #xxx
- Breaking?: last paragraph: BREAKING CHANGE: <describe what changed + link for details>
Testing
- Unit test added. Prefer to add a new test rather than modify existing tests
- CLI or init templates change? Re-run/add CLI integration tests
Documentation
- README: update module README to describe new features
- API docs: public APIs must be documented. Copy from official AWS docs when possible
- Design: for significant features, follow design process

mergify · 2019-12-16T13:53:42Z

Thanks so much for taking the time to contribute to the AWS CDK ❤️

We will shortly assign someone to review this pull request and help get it
merged. In the meantime, please take a minute to make sure you follow this
checklist:

PR title type(scope): text
- type: fix, feat, refactor go into CHANGELOG, chore is hidden
- scope: name of module without aws- or cdk- prefix or postfix (e.g. s3 instead of aws-s3-deployment)
- text: use all lower-case, do not end with a period, do not include issue refs
PR Description
- Rationale: describe rationale of change and approach taken
- Issues: indicate issues fixed via: fixes #xxx or closes #xxx
- Breaking?: last paragraph: BREAKING CHANGE: <describe what changed + link for details>
Testing
- Unit test added. Prefer to add a new test rather than modify existing tests
- CLI or init templates change? Re-run/add CLI integration tests
Documentation
- README: update module README to describe new features
- API docs: public APIs must be documented. Copy from official AWS docs when possible
- Design: for significant features, follow design process

eladb · 2019-12-16T14:22:55Z

@shivlaks @nija-at what's up here? Is this ready for merge?

mergify · 2019-12-16T14:39:36Z

Thanks so much for taking the time to contribute to the AWS CDK ❤️

We will shortly assign someone to review this pull request and help get it
merged. In the meantime, please take a minute to make sure you follow this
checklist:

PR title type(scope): text
- type: fix, feat, refactor go into CHANGELOG, chore is hidden
- scope: name of module without aws- or cdk- prefix or postfix (e.g. s3 instead of aws-s3-deployment)
- text: use all lower-case, do not end with a period, do not include issue refs
PR Description
- Rationale: describe rationale of change and approach taken
- Issues: indicate issues fixed via: fixes #xxx or closes #xxx
- Breaking?: last paragraph: BREAKING CHANGE: <describe what changed + link for details>
Testing
- Unit test added. Prefer to add a new test rather than modify existing tests
- CLI or init templates change? Re-run/add CLI integration tests
Documentation
- README: update module README to describe new features
- API docs: public APIs must be documented. Copy from official AWS docs when possible
- Design: for significant features, follow design process

mergify · 2019-12-16T14:53:14Z

Thanks so much for taking the time to contribute to the AWS CDK ❤️

We will shortly assign someone to review this pull request and help get it
merged. In the meantime, please take a minute to make sure you follow this
checklist:

PR title type(scope): text
- type: fix, feat, refactor go into CHANGELOG, chore is hidden
- scope: name of module without aws- or cdk- prefix or postfix (e.g. s3 instead of aws-s3-deployment)
- text: use all lower-case, do not end with a period, do not include issue refs
PR Description
- Rationale: describe rationale of change and approach taken
- Issues: indicate issues fixed via: fixes #xxx or closes #xxx
- Breaking?: last paragraph: BREAKING CHANGE: <describe what changed + link for details>
Testing
- Unit test added. Prefer to add a new test rather than modify existing tests
- CLI or init templates change? Re-run/add CLI integration tests
Documentation
- README: update module README to describe new features
- API docs: public APIs must be documented. Copy from official AWS docs when possible
- Design: for significant features, follow design process

mergify · 2019-12-16T15:18:33Z

Thanks so much for taking the time to contribute to the AWS CDK ❤️

We will shortly assign someone to review this pull request and help get it
merged. In the meantime, please take a minute to make sure you follow this
checklist:

PR title type(scope): text
- type: fix, feat, refactor go into CHANGELOG, chore is hidden
- scope: name of module without aws- or cdk- prefix or postfix (e.g. s3 instead of aws-s3-deployment)
- text: use all lower-case, do not end with a period, do not include issue refs
PR Description
- Rationale: describe rationale of change and approach taken
- Issues: indicate issues fixed via: fixes #xxx or closes #xxx
- Breaking?: last paragraph: BREAKING CHANGE: <describe what changed + link for details>
Testing
- Unit test added. Prefer to add a new test rather than modify existing tests
- CLI or init templates change? Re-run/add CLI integration tests
Documentation
- README: update module README to describe new features
- API docs: public APIs must be documented. Copy from official AWS docs when possible
- Design: for significant features, follow design process

shivlaks · 2020-01-22T18:44:06Z

@shivlaks @nija-at what's up here? Is this ready for merge?

@eladb @nija-at can I get another review on this, is there anything I've missed?

mergify · 2020-01-22T19:06:23Z

Title does not follow the guidelines of Conventional Commits. Please adjust title before merge.

aws-cdk-automation · 2020-01-22T19:22:06Z

AWS CodeBuild CI Report

Result: SUCCEEDED
Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

eladb

looks good go ahead.

please move it to the RFC repo after merge and create a tracking issue following the RFC workflow.

shivlaks added 4 commits September 12, 2019 07:14

rfc: publish cdk construct tree

dc41934

cleaning up some whitespace

ba9956f

getting rid of placeholder construct tree map as it's a little confusing

9ae5abc

update properties, included a placeholder sample of the schema

0b625a4

shivlaks added the pr/do-not-merge This PR should not be merged at this time. label Sep 13, 2019

shivlaks requested review from a team September 13, 2019 00:24

mergify bot added the automerge-enabled label Sep 13, 2019

NGL321 approved these changes Sep 13, 2019

View reviewed changes

NGL321 removed the automerge-enabled label Sep 13, 2019

NGL321 assigned ghost Sep 13, 2019

ghost approved these changes Sep 13, 2019

View reviewed changes

eladb reviewed Sep 13, 2019

View reviewed changes

eladb suggested changes Sep 13, 2019

View reviewed changes

nija-at suggested changes Sep 17, 2019

View reviewed changes

nija-at mentioned this pull request Sep 22, 2019

feat: publish construct hierarchy with metadata to cloud assembly #4194

Merged

NGL321 added the contribution/core This is a PR that came from AWS. label Sep 27, 2019

clean up formatting to address feedback

88f173f

shivlaks added 3 commits October 13, 2019 01:27

add experimental header, rename renderedView -> properties, added pla…

3e55a1e

…ceholders to describe source of construct properties

updates to tree, removed id as a nested attribute, created placeholde…

46a7222

…rs to fill in source of metadata

moving errors/warnings as additional functionality. filling in source…

830c13a

… columns for construct properties

simplify and rename attributes interface. Updated tree to share type …

9191416

…and properties by naming convention

eladb added the management/rfc request for comments label Dec 16, 2019

shivlaks requested review from nija-at and eladb January 22, 2020 18:43

Merge branch 'master' into shivlaks/rfc-construct-tree

ff1b8c0

shivlaks assigned eladb and unassigned ghost Jan 22, 2020

eladb changed the title ~~rfc: publish cdk construct tree~~ rfc: tree.json Jan 22, 2020

eladb approved these changes Jan 22, 2020

View reviewed changes

shivlaks merged commit 2ab25bd into master Jan 23, 2020

shivlaks deleted the shivlaks/rfc-construct-tree branch January 23, 2020 20:19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

rfc: tree.json #4053

rfc: tree.json #4053

shivlaks commented Sep 13, 2019

mergify bot commented Sep 13, 2019

ghost left a comment

eladb left a comment

nija-at Sep 17, 2019

nija-at Sep 17, 2019

nija-at Sep 17, 2019

nija-at Sep 17, 2019

aws-cdk-automation commented Oct 1, 2019

aws-cdk-automation commented Oct 17, 2019

aws-cdk-automation commented Oct 17, 2019

aws-cdk-automation commented Nov 5, 2019

mergify bot commented Dec 16, 2019

mergify bot commented Dec 16, 2019

mergify bot commented Dec 16, 2019

eladb commented Dec 16, 2019

mergify bot commented Dec 16, 2019

mergify bot commented Dec 16, 2019

mergify bot commented Dec 16, 2019

shivlaks commented Jan 22, 2020

mergify bot commented Jan 22, 2020

aws-cdk-automation commented Jan 22, 2020

eladb left a comment

rfc: tree.json #4053

rfc: tree.json #4053

Conversation

shivlaks commented Sep 13, 2019

mergify bot commented Sep 13, 2019

ghost left a comment

Choose a reason for hiding this comment

eladb left a comment

Choose a reason for hiding this comment

nija-at Sep 17, 2019

Choose a reason for hiding this comment

nija-at Sep 17, 2019

Choose a reason for hiding this comment

nija-at Sep 17, 2019

Choose a reason for hiding this comment

nija-at Sep 17, 2019

Choose a reason for hiding this comment

aws-cdk-automation commented Oct 1, 2019

AWS CodeBuild CI Report

aws-cdk-automation commented Oct 17, 2019

AWS CodeBuild CI Report

aws-cdk-automation commented Oct 17, 2019

AWS CodeBuild CI Report

aws-cdk-automation commented Nov 5, 2019

AWS CodeBuild CI Report

mergify bot commented Dec 16, 2019

mergify bot commented Dec 16, 2019

mergify bot commented Dec 16, 2019

eladb commented Dec 16, 2019

mergify bot commented Dec 16, 2019

mergify bot commented Dec 16, 2019

mergify bot commented Dec 16, 2019

shivlaks commented Jan 22, 2020

mergify bot commented Jan 22, 2020

aws-cdk-automation commented Jan 22, 2020

AWS CodeBuild CI Report

eladb left a comment

Choose a reason for hiding this comment