Merge branch 'master' into sagemaker-l2

.github/ISSUE_TEMPLATE/tracking.md

@@ -21,7 +21,13 @@ service’s CDK Construct Library API reference page.
 
 
 [AWS Docs](url)  <!-- replace `url` with link to the relevant AWS Docs -->
-[CDK API Reference](url) <!-- replace `url` with link to the service's CDK API reference -->
+
+### Maturity: CloudFormation Resources Only
+<!--
+The valid maturity states are: CloudFormation Resources Only, Experimental, Developer Preview, Stable
+-->
+
+See the [AWS Construct Library Module Lifecycle doc](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0107-construct-library-module-lifecycle.md) for more information about maturity levels.
 
 
 ### Implementation:
@@ -31,6 +37,7 @@ Checklist of use cases, constructs, features (such as grant methods) that will s
 - [ ] 
 - [ ]
 -->
+[CDK API Reference](url) <!-- replace `url` with link to the service's CDK API reference -->
 
 
 

README.md

@@ -30,7 +30,8 @@ The CDK is available in the following languages:
 [API Reference](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-construct-library.html) |
 [Examples](https://github.com/aws-samples/aws-cdk-examples) |
 [Getting Help](#getting-help) |
-[RFCs](https://github.com/aws/aws-cdk-rfcs)
+[RFCs](https://github.com/aws/aws-cdk-rfcs) |
+[Roadmap](https://github.com/aws/aws-cdk/ROADMAP.md)
 
 Developers use the [CDK framework] in one of the
 supported programming languages to define reusable cloud components called [constructs], which
@@ -122,6 +123,13 @@ We welcome community contributions and pull requests. See
 [CONTRIBUTING](./CONTRIBUTING.md) for information on how to set up a development
 environment and submit code.
 
+## Roadmap
+
+The [AWS CDK Roadmap project board] lets developers know about our upcoming features and priorities to help them plan how to best leverage the CDK and identify opportunities to contribute to the project. See [ROADMAP] for more information and FAQs.
+
+[AWS CDK Roadmap project board]: https://github.com/orgs/aws/projects/7
+[Roadmap]: (https://github.com/aws/aws-cdk/ROADMAP.md)
+
 ## License
 
 The AWS CDK is distributed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0).

ROADMAP.md

@@ -0,0 +1,86 @@
+# AWS CDK Roadmap
+
+The [AWS CDK Roadmap] lets developers know about our upcoming features and priorities to help them plan how to best leverage the CDK and identify opportunities to contribute to the project. The roadmap provides a high-level view of our work in progress across the [aws-cdk], [aws-cdk-rfcs], and [jsii] repositories, and creates an opportunity for customers to engage in a conversation with AWS CDK engineers to give us direct feedback.
+
+[AWS CDK Roadmap]: https://github.com/orgs/aws/projects/7
+[aws-cdk]: https://github.com/aws/aws-cdk
+[aws-cdk-rfcs]: https://github.com/aws/aws-cdk-rfcs
+[jsii]: https://github.com/aws/jsii
+
+## Roadmap FAQs
+
+**Q: How do you manage the roadmap?**
+
+A: We know that our customers are making decisions and plans based on what we
+are developing, and we want to provide the information they need to be successful. Our roadmap management tenets are:
+
+* **Be transparent** with customers about the AWS CDK team’s work in progress
+* **Listen to customers,** allowing them to participate in design decisions and to vote on and propose new AWS CDK
+  features. We will periodically re-prioritize the roadmap based on customer feedback
+* **Stay up-to-date,** or we will lose customer trust
+* **Provide the right level of detail** so customers can easily see what we’re working on at a glance, without being
+  overwhelmed by minutiae
+* **Guide the community** on what AWS CDK constructs or features to contribute without the risk of conflicting with work
+  already in progress
+
+**Q: What do the roadmap project board columns mean?**
+
+A: There are four columns on the roadmap project board:
+
+* **Researching** - We’re thinking about it, but cannot commit if, or when, we will work on items in this list.
+  This means we are still designing the feature and evaluating how it might work. This is the phase when we collect
+  customer use cases and feedback on how they want to see something implemented. There is no firm commitment to deliver
+  functionality listed in the Researching column, and there might be situations that require us to move items from the
+  roadmap back to the backlog.
+* **We’re working on it** - In progress, but further out. We have made an implied commitment to work on items in this
+  bucket, they have some level of design spec’ed out, and a developer assigned to them. Items might linger in this
+  bucket as we work through the implementation details, or scope stuff out. Think several months out until a developer
+  preview release, give or take.
+* **Developer preview** - It’s available now as a release candidate. Items will spend extended periods of time in
+  developer preview as we conduct user acceptance testing and accumulate sufficient usage to declare the API stable and
+  ready for general availability. We will only make breaking changes to developer preview modules when we need to address unforeseen use cases or issues. Not all
+  features, such as enhancements to the CDK CLI, will have a developer preview phase. In these cases the tracking issue
+  is moved directly to the Shipped bucket when released.
+* **Shipped** - It’s available now, fully supported by AWS, and we guarantee the API is stable and safe to use in
+  production.
+
+**Q: How do items on the roadmap move across the project board?**
+
+A:  The [AWS Construct Library module lifecycle
+document](https://github.com/aws/aws-cdk-rfcs/blob/master/text/0107-construct-library-module-lifecycle.md) describes how
+we graduate packages from experimental, to developer preview, to generally available.
+
+**Q: Why are there no dates on this roadmap?**
+
+A: Security and operational stability are our main priority and we will not ship a feature until these criteria are met,
+therefore we generally don’t provide specific target dates for releases.
+
+**Q: Is every feature on the roadmap?**
+
+A: The AWS Cloud Development Kit roadmap provides transparency on our priority for adding new programming languages,
+developer experience improvements, and service coverage in the AWS Construct Library. The AWS CDK toolkit and AWS
+Construct Library are such a large surface areas we are intentionally keeping the roadmap at a high-level, so not every
+CDK feature request will appear on the roadmap. Instead, the roadmap will include a tracking issue
+for each deliverable that provides a feature overview and contains links to relevant, more granular issues and pull
+requests. If you want to track the status of a specific issue or pull request, you can do so by monitoring that work
+item in the [aws-cdk] GitHub repository.
+
+**Q: What is a tracking issue?**
+
+A: We create a tracking issue for each CDK feature, AWS Construct Library module, and jsii-supported programming language. Tracking issues provide a brief summary of the feature and a consolidated view of the work scoped for the release. They include links to design documentation, implementation details, and relevant issues. Tracking issues are living documents that start from a basic template and grow more robust over time as we experiment and learn. You can easily find tracking issues by filtering on the [management/tracking label](https://github.com/aws/aws-cdk/labels/management%2Ftracking).
+
+**Q: How can I provide feedback on the roadmap or ask for more information about a feature?**
+
+A: Please open an issue!
+
+**Q: How can I request a feature be added to the roadmap?**
+
+A: Please open an issue! Community submitted issues will be tagged “feature-request” and will be reviewed by the team.
+
+**Q: Can I “+1” tracking issues and feature requests?**
+
+A: We strongly encourage you to do so, as it helps us understand which issues will have the broadest impact. You can navigate to the issue details page and add a reaction. There are six types of reactions (thumbs up “+1”, thumbs down “-1”, confused, heart, watching, laugh, and hooray) you can use to help us decide which items will benefit you most.
+
+**Q: Will you accept a pull request to the aws-cdk repo?**
+
+A: Yes! We take PRs very seriously and will review for inclusion. You can read how to contribute to the CDK [here](https://github.com/aws/aws-cdk/blob/master/CONTRIBUTING.md).

design/aws-guidelines.md

@@ -437,7 +437,7 @@ class ImportedFoo extends FooBase {
 - [ ] Metrics (`metricXxx`)
 - [ ] Events (`onXxx`)
 - [ ] Security Groups (`connections`)
-- [ ] Pipeline Actions (`addToPipline`)
+- [ ] Pipeline Actions (`addToPipeline`)
 - [ ] SNS Targets
 - [ ] `_asFooTarget`
 - [ ] TODO: other cross AWS patterns

design/cloud-assembly.md

@@ -62,7 +62,7 @@ In other words, *Logical IDs* are expected to match the following regular expres
 ```
 
 ### Droplet
-Clouds are made of Droplets. Thet are the building blocks of *Cloud Assemblies*. They model a part of the
+Clouds are made of Droplets. They are the building blocks of *Cloud Assemblies*. They model a part of the
 *cloud application* that can be deployed independently, provided its dependencies are fulfilled. Droplets are specified
 using [JSON] objects that **MUST** conform to the following schema:
 
@@ -197,7 +197,7 @@ Key   |Type    |Description
 Here is a schematic example:
 ```js
 {
-  // When this attestation doucment was created
+  // When this attestation document was created
   "timestamp": "2018-11-15T11:08:52",
   // The hashing algorithm for the attestation is SHA256
   "algorithm": "SHA256",
@@ -216,7 +216,7 @@ Here is a schematic example:
 ```
 
 Once the attestation is ready, it is digitally *signed* using the configured [PGP][RFC 4880] key. The key **MUST** be
-valid as of the `timestamp` field included in the attestation. The siganture **MUST** not be detached, and is
+valid as of the `timestamp` field included in the attestation. The signature **MUST** not be detached, and is
 **RECOMMENDED** to use the *cleartext signature framework* described in section 7 of [RFC 4880] so the attestation can
 be read by a human.
 
@@ -229,7 +229,7 @@ Deployment systems that support verifying signed *Cloud Assemblies*:
   be returned when attempting to deploy an un-signed *Cloud Assembly*.
 * **MUST** verify the integrity and authenticity of signed *Cloud Assemblies* prior to attempting to load any file
   included in it, except for `signature.asc`.
-  * An error **MUST** be raised if the *Cloud Assembly*'s integirty is not verified by the signature.
+  * An error **MUST** be raised if the *Cloud Assembly*'s integrity is not verified by the signature.
   * An error **MUST** be raised if the [PGP][RFC 4880] key has expired according to the signature timestamp.
   * An error **MUST** be raised if the [PGP][RFC 4880] key is known to have been revoked. Deployment systems **MAY**
     trust locally available information pertaining to the key's validity.
@@ -470,4 +470,4 @@ Hash: SHA256
 [ISO/IEC 21320-1:2015]: https://www.iso.org/standard/60101.html
 [JSON]: https://www.json.org
 [RFC 4880]: https://tools.ietf.org/html/rfc4880
-[ISO 8601]: https://www.iso.org/standard/40874.html
+[ISO 8601]: https://www.iso.org/standard/40874.html

design/code-asset-metadata.md

@@ -56,8 +56,8 @@ well as through the key `assetMetadata` in `cdk.json`. Very similar design to ho
 
 We considered alternatives that will "enforce" the embedding of metadata when an asset is referenced by a resource. Since
 a single asset can be referenced by multiple resources, it means that the _relationship_ is what should trigger the
-metadata addition. There currently isn't support in the framework for such hooks, but there is a possiblility that
-the changes in [#1436](https://github.com/aws/aws-cdk/pull/1436) might enable hooking into the relationnship, and then we might be able to use this mechanism to produce the metadata.
+metadata addition. There currently isn't support in the framework for such hooks, but there is a possibility that
+the changes in [#1436](https://github.com/aws/aws-cdk/pull/1436) might enable hooking into the relationship, and then we might be able to use this mechanism to produce the metadata.
 
 Having said that, the need to embed asset metadata on resources is mainly confined to authors of L2 constructs, and not applicable for the general user population, so the value of automation is not high.