chore(guidelines): guidance on which constructs are included in the CDK

DESIGN_GUIDELINES.md

@@ -1,5 +1,65 @@
 # AWS Construct Library Design Guidelines
 
+- [AWS Construct Library Design Guidelines](#aws-construct-library-design-guidelines)
+  - [What's Included](#what-s-included)
+  - [API Design](#api-design)
+    - [Modules](#modules)
+    - [Construct Class](#construct-class)
+    - [Construct Interface](#construct-interface)
+      - [Owned vs. Unowned Constructs](#owned-vs-unowned-constructs)
+      - [Abstract Base](#abstract-base)
+    - [Props](#props)
+      - [Types](#types)
+      - [Defaults](#defaults)
+      - [Flat](#flat)
+      - [Concise](#concise)
+      - [Naming](#naming)
+      - [Property Documentation](#property-documentation)
+      - [Enums](#enums)
+      - [Unions](#unions)
+    - [Attributes](#attributes)
+    - [Configuration](#configuration)
+      - [Prefer Additions](#prefer-additions)
+      - [Dropped Mutations](#dropped-mutations)
+    - [Factories](#factories)
+    - [Imports](#imports)
+      - [“from” Methods](#-from--methods)
+      - [From-attributes](#from-attributes)
+    - [Roles](#roles)
+    - [Resource Policies](#resource-policies)
+    - [VPC](#vpc)
+    - [Grants](#grants)
+    - [Metrics](#metrics)
+    - [Events](#events)
+    - [Connections](#connections)
+    - [Integrations](#integrations)
+    - [State](#state)
+    - [Physical Names - TODO](#physical-names---todo)
+    - [Tags](#tags)
+    - [Secrets](#secrets)
+  - [Project Structure](#project-structure)
+    - [Code Organization](#code-organization)
+  - [Implementation](#implementation)
+    - [General Principles](#general-principles)
+    - [Construct IDs](#construct-ids)
+    - [Errors](#errors)
+      - [Input Validation](#input-validation)
+      - [Avoid Errors If Possible](#avoid-errors-if-possible)
+      - [Never Catch Exceptions](#never-catch-exceptions)
+      - [Post Validation](#post-validation)
+      - [Attached Errors/Warnings](#attached-errors-warnings)
+    - [Tokens](#tokens)
+  - [Documentation](#documentation)
+    - [Inline Documentation](#inline-documentation)
+    - [Readme](#readme)
+  - [Testing](#testing)
+    - [Unit tests](#unit-tests)
+    - [Integration tests](#integration-tests)
+    - [Versioning](#versioning)
+  - [Naming & Style](#naming---style)
+    - [Naming Conventions](#naming-conventions)
+    - [Coding Style](#coding-style)
+
 The AWS Construct Library is a rich class library of CDK constructs which
 represent all resources offered by the AWS Cloud and higher-level constructs for
 achieving common tasks.
@@ -58,6 +118,73 @@ allows the library to be used from all supported programming languages. jsii
 poses restrictions on language features that cannot be idiomatically represented
 in target languages.
 
+## What's Included
+
+The AWS Construct Library, which is shipped as part of the AWS CDK constructs
+representing AWS resources.
+
+The AWS Construct Library has multiple layers of constructs, beginning
+with low-level constructs, which we call _CFN Resources_ (or L1, short for
+"level 1") or CFN Resources (short for CloudFormation). These constructs
+directly represent all resources available in AWS CloudFormation. CFN Resources
+are periodically generated from the AWS CloudFormation Resource
+Specification. They are named **Cfn**_Xyz_, where _Xyz_ is name of the
+resource. For example, CfnBucket represents the AWS::S3::Bucket AWS
+CloudFormation resource. When you use Cfn resources, you must explicitly
+configure all resource properties, which requires a complete understanding of
+the details of the underlying AWS CloudFormation resource model.
+
+The next level of constructs, L2, also represent AWS resources, but with a
+higher-level, intent-based API. They provide similar functionality, but provide
+the defaults, boilerplate, and glue logic you'd be writing yourself with a CFN
+Resource construct. L2 constructs offer convenient defaults and reduce the need
+to know all the details about the AWS resources they represent, while providing
+convenience methods that make it simpler to work with the resource. For example,
+the `s3.Bucket` class represents an Amazon S3 bucket with additional properties
+and methods, such as `bucket.addLifeCycleRule()`, which adds a lifecycle rule to
+the bucket.
+
+Examples of behaviors that an L2 commonly include:
+
+- Strongly-typed modeling of the underlying L1 properties
+- Methods for integrating other AWS resources (e.g., adding an event notification to
+  an S3 bucket).
+- Modeling of permissions and resource policies
+- Modeling of metrics
+
+In addition to the above, some L2s may introduce more complex and
+helpful functionality, either part of the original L2 itself, or as part of a
+separate construct. The most common form of these L2s are integration constructs
+that model interactions between different services (e.g., SNS publishing to SQS,
+CodePipeline actions that trigger Lambda functions).
+
+The next level of abstraction present within the CDK are what we designate as
+"L2.5s": a step above the L2s in terms of abstraction, but not quite at the
+level of complete patterns or applications.  These constructs still largely
+focus on a single logical resource -- in constrast to "patterns" which combine
+multiple resources -- but are customized for a specific common usage scenario of
+an L2. Examples of L2.5s in the CDK are `aws-apigateway.LambdaRestApi`,
+`aws-lambda-nodejs.NodeJsFunction`, and `aws-rds.ServerlessCluster`.
+
+L2.5 constructs will be considered for inclusion in the CDK if they...
+
+- cover a common usage scenario that can be used by a significant portion of
+  the community;
+- provide significant ease of use over the base L2 (via usage-specific defaults
+  convenience methods or improved strong-typing);
+- simplify or enable another L2 within the CDK
+
+The CDK also currently includes some even higher-level constructs, which we call
+patterns. These constructs often involve multiple kinds of resources and are
+designed to help you complete common tasks in AWS or represent entire
+applications. For example, the
+`aws-ecs-patterns.ApplicationLoadBalancedFargateService` construct represents an
+architecture that includes an AWS Fargate container cluster employing an
+Application Load Balancer (ALB). These patterns are typically difficult to
+design to be one-size-fits-all and are best suited to be published as separate
+libraries, rather than included directly in the CDK. The patterns that currently
+exist in the CDK will be removed in the next CDK major version (CDKv2).
+
 ## API Design
 
 ### Modules