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

…DK (aws#13218)

Adding a section of general guidance in the DESIGN_GUIDELINES to explain the L1,
L2, and beyond constructs, and what types of behaviors L2s should include versus
what types likely belong in separate repositories.

This guidance is by no means complete or without controversy. I expect pushback
and hope for both more supporting examples as well as counter examples.


----

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

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`, `aws-rds.ServerlessCluster` and `eks.FargateCluster`.
+
+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