recent doc changes

v1/best-practices.md

@@ -31,7 +31,7 @@ Development teams should be able use their own accounts for testing and have the
 
 ## Coding best practices<a name="best-practices-code"></a>
 
- This section presents best practices for organizing your AWS CDK code\. The diagram below shows the relationship between a team and that team's code repositories, packages, applications, and construct libraries\. 
+This section presents best practices for organizing your AWS CDK code\. The diagram below shows the relationship between a team and that team's code repositories, packages, applications, and construct libraries\. 
 
 ![\[Image NOT FOUND\]](http://docs.aws.amazon.com/cdk/v1/guide/images/code-organization.jpg)
 
@@ -75,11 +75,15 @@ A construct that is self\-contained, in other words that completely describes a
 
 ## Construct best practices<a name="best-practices-constructs"></a>
 
- This section contains best practices for developing constructs\. Constructs are reusable, composable modules that encapsulate resources, and the building blocks of AWS CDK apps\.
+This section contains best practices for developing constructs\. Constructs are reusable, composable modules that encapsulate resources, and the building blocks of AWS CDK apps\.
 
-### Model your app through constructs, not stacks<a name="best-practices-constructs-model"></a>
+### Model with constructs, deploy with stacks<a name="best-practices-constructs-model"></a>
 
-When breaking down your application into logical units, represent each unit as a descendant of [https://docs.aws.amazon.com/cdk/api/v1/docs/constructs.Construct.html](https://docs.aws.amazon.com/cdk/api/v1/docs/constructs.Construct.html) and not of [https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_core.Stack.html](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_core.Stack.html)\. Stacks are a unit of deployment, and so tend to be oriented to specific applications\. By using constructs instead of stacks, you give yourself and your users the flexibility to build stacks in the way that makes the most sense for each deployment scenario\. For example, you could compose multiple constructs into a `DevStack` with some configuration for development environments and then have a different composition for your `ProdStack`\.
+Stacks are the unit of deployment: everything in a stack is deployed together\. So when building your application's higher\-level logical units from multiple AWS resources, represent each logical unit as a [https://docs.aws.amazon.com/cdk/api/v1/docs/constructs.Construct.html](https://docs.aws.amazon.com/cdk/api/v1/docs/constructs.Construct.html), not as a [https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_core.Stack.html](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_core.Stack.html)\. Use stacks only to describe how your constructs should be composed and connected for your various deployment scenarios\.
+
+If one of your logical units is a Web site, for example, the constructs that make it up \(Amazon S3 bucket, API Gateway, Lambda functions, Amazon RDS tables, etc\.\) should be composed into a single high\-level construct, and then that construct should be instantiated in one or more stacks for deployment\.
+
+By using constructs for building and stacks for deploying, you improve reuse potential of your infrastructure and give yourself more flexibility in how it is deployed\.
 
 ### Configure with properties and methods, not environment variables<a name="best-practices-constructs-config"></a>
 
@@ -172,9 +176,9 @@ If you require developers to always use predefined roles that were created by a
 
 ### Model all production stages in code<a name="best-practices-apps-stages"></a>
 
- In traditional AWS CloudFormation scenarios, your goal is to produce a single artifact that is parameterized so that it can be deployed to various target environments after applying configuration values specific to those environments\. In the CDK, you can, and should, build that configuration right into your source code\. Create a stack for your production environment, and a separate one for each of your other stages, and put the configuration values for each right there in the code\. Use services like [Secrets Manager](https://aws.amazon.com/secrets-manager/) and [Systems Manager](https://aws.amazon.com/systems-manager/) Parameter Store for sensitive values that you don't want to check in to source control, using the names or ARNs of those resources\.
+In traditional AWS CloudFormation scenarios, your goal is to produce a single artifact that is parameterized so that it can be deployed to various target environments after applying configuration values specific to those environments\. In the CDK, you can, and should, build that configuration right into your source code\. Create a stack for your production environment, and a separate one for each of your other stages, and put the configuration values for each right there in the code\. Use services like [Secrets Manager](https://aws.amazon.com/secrets-manager/) and [Systems Manager](https://aws.amazon.com/systems-manager/) Parameter Store for sensitive values that you don't want to check in to source control, using the names or ARNs of those resources\.
 
- When you synthesize your application, the cloud assembly created in the `cdk.out` folder contains a separate template for each environment\. Your entire build is deterministic: there are no out\-of\-band changes to your application, and any given commit always yields the exact same AWS CloudFormation template and accompanying assets, which makes unit testing much more reliable\. 
+When you synthesize your application, the cloud assembly created in the `cdk.out` folder contains a separate template for each environment\. Your entire build is deterministic: there are no out\-of\-band changes to your application, and any given commit always yields the exact same AWS CloudFormation template and accompanying assets, which makes unit testing much more reliable\. 
 
 ### Measure everything<a name="best-practices-apps-measure"></a>
 

v1/cli.md

@@ -728,8 +728,10 @@ Options:
                                             permissions, modern bootstrapping
                                             only)                      [boolean]
 
-      --qualifier                           Unique string to distinguish
-                                            multiple bootstrap stacks   [string]
+      --qualifier                           String which must be unique for each
+                                            bootstrap stack. You must configure
+                                            it on your CDK app if you change
+                                            this from the default.      [string]
 
       --public-access-block-configuration   Block public access configuration
                                             on CDK toolkit bucket (enabled by

v1/constructs.md

@@ -19,7 +19,7 @@ There are three different levels of constructs in this library, beginning with l
 
 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\. AWS 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](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_aws-s3.Bucket.html) class represents an Amazon S3 bucket with additional properties and methods, such as [bucket\.addLifeCycleRule\(\)](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_aws-s3.Bucket.html#add-wbr-lifecycle-wbr-rulerule), which adds a lifecycle rule to the bucket\.
 
-Finally, the AWS Construct Library includes even higher\-level constructs, which we call *patterns*\. These constructs are designed to help you complete common tasks in AWS, often involving multiple kinds of resources\. For example, the [aws\-ecs\-patterns\.ApplicationLoadBalancedFargateService](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_aws-ecs-patterns.ApplicationLoadBalancedFargateService.html) construct represents an architecture that includes an AWS Fargate container cluster employing an Application Load Balancer \(ALB\)\. The [aws\-apigateway\.LambdaRestApi](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_aws-apigateway.LambdaRestApi.html) construct represents an Amazon API Gateway API that's backed by an AWS Lambda function\.
+Finally, the AWS Construct Library includes L3 constructs, which we call *patterns*\. These constructs are designed to help you complete common tasks in AWS, often involving multiple kinds of resources\. For example, the [aws\-ecs\-patterns\.ApplicationLoadBalancedFargateService](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_aws-ecs-patterns.ApplicationLoadBalancedFargateService.html) construct represents an architecture that includes an AWS Fargate container cluster employing an Application Load Balancer \(ALB\)\. The [aws\-apigateway\.LambdaRestApi](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_aws-apigateway.LambdaRestApi.html) construct represents an Amazon API Gateway API that's backed by an AWS Lambda function\.
 
 For more information about how to navigate the library and discover constructs that can help you build your apps, see the [API Reference](https://docs.aws.amazon.com/cdk/api/v1/docs/aws-construct-library.html)\.
 
@@ -746,6 +746,9 @@ public class NotifyingBucket : Construct
 
 ------
 
+**Note**  
+Our `NotifyingBucket` construct inherits not from `Bucket` but rather from `Construct`\. We are using composition, not inheritance, to bundle an Amazon S3 bucket and an Amazon SNS topic together\. In general, composition is preferred over inheritance when developing AWS CDK constructs\.
+
 The `NotifyingBucket` constructor has a typical construct signature: `scope`, `id`, and `props`\. The last argument, `props`, is optional \(gets the default value `{}`\) because all props are optional\. \(The base `Construct` class does not take a `props`argument\.\) You could define an instance of this construct in your app without `props`, for example: 
 
 ------
@@ -880,7 +883,7 @@ class NotifyingBucket(core.Construct):
 #### [ Java ]
 
 ```
-public class NotifyingBucket extends Bucket {
+public class NotifyingBucket extends Construct {
 
     public Topic topic = null;
     

v1/context.md

@@ -1,11 +1,21 @@
 # Runtime context<a name="context"></a>
 
-Context values are key\-value pairs that can be associated with a stack or construct\. The AWS CDK uses context to cache information from your AWS account, such as the Availability Zones in your account or the Amazon Machine Image \(AMI\) IDs used to start your instances\. [Feature flags](featureflags.md) are also context values\. You can create your own context values for use by your apps or constructs\.
+Context values are key\-value pairs that can be associated with an app, stack, or construct\. The AWS CDK uses context to cache information from your AWS account, such as the Availability Zones in your account or the Amazon Machine Image \(AMI\) IDs used to start your instances\. [Feature flags](featureflags.md) are also context values\. You can create your own context values for use by your apps or constructs\.
 
 Context keys are strings, and values may be any type supported by JSON: numbers, strings, arrays, or objects\.
 
+If your constructs create their own context values, incorporate your library's package name in its keys so they won't conflict with other package's context values\.
+
+Since most context values are associated with a particular AWS environment, and a given CDK app can be deployed in more than one environment, it is important to be able to set context values for each environment\. This is achieved by including the AWS account and region in the context key, so that values from different environments do not conflict\.
+
+The context key below illustrates the format used by the AWS CDK, including the account and region\.
+
+```
+availability-zones:account=123456789012:region=eu-central-1
+```
+
 **Important**  
-Context values are managed by the AWS CDK and its constructs, including constructs you may write\. You should not attempt to add context values manually\. It is useful to review `cdk.context.json` to see what values are being cached; by convention, the keys start with the name of the CDK package that set them\. You should follow this convention when setting your own values\.
+Context values are managed by the AWS CDK and its constructs, including constructs you may write\. In general, you should not add or change context values by manually editing files\. It can be useful to review `cdk.context.json` to see what values are being cached\.
 
 ## Construct context<a name="context_construct"></a>
 
@@ -19,7 +29,7 @@ Context values can be provided to your AWS CDK app in six different ways:
 
 The project file `cdk.context.json` is where the AWS CDK caches context values retrieved from your AWS account\. This practice avoids unexpected changes to your deployments when, for example, a new Amazon Linux AMI is released, changing your Auto Scaling group\. The AWS CDK does not write context data to any of the other files listed\. 
 
-We recommend that your project's context files be placed under version control along with the rest of your application, as the information in them is part of your app's state and is critical to being able to synthesize and deploy consistently\. It is also critical to successful automated deployment of stacks that rely on context values \(for example, using [CDK Pipelines](cdk_pipeline.md)\)\.
+We recommend that `cdk.context.json` be placed under version control along with the rest of your application, as the information in them is part of your app's state and is critical to being able to synthesize and deploy consistently\. It is also critical to successful automated deployment of stacks that rely on context values \(for example, using [CDK Pipelines](cdk_pipeline.md)\)\.
 
 Context values are scoped to the construct that created them; they are visible to child constructs, but not to siblings\. Context values set by the AWS CDK Toolkit \(the cdk command\), whether automatically, from a file, or from the \-\-context option, are implicitly set on the `App` construct, and so are visible to every construct in the app\.
 

v1/work-with-cdk-java.md

@@ -30,7 +30,7 @@ If you are using an IDE, you can now open or import the project\. In Eclipse, fo
 
 ## Managing AWS Construct Library modules<a name="java-managemodules"></a>
 
-Use Maven to install AWS Construct Library packages, which are in the group `software.amazon.awscdk` and named with a short version \(no AWS or Amazon prefix\) of their service's name\. For example, the Maven artifact ID for Amazon S3 is `s3`\. [Search the Maven Central Repository](https://search.maven.org/search?q=sg:oftware.amazon.awscdk) to find the names of all AWS CDK and AWS Construct Module libraries\.
+Use Maven to install AWS Construct Library packages, which are in the group `software.amazon.awscdk` and named with a short version \(no AWS or Amazon prefix\) of their service's name\. For example, the Maven artifact ID for Amazon S3 is `s3`\. [Search the Maven Central Repository](https://search.maven.org/search?q=software.amazon.awscdk) to find the names of all AWS CDK and AWS Construct Module libraries\.
 
 **Note**  
 The [Java edition of the CDK API Reference](https://docs.aws.amazon.com/cdk/api/v1/java/index.html) also shows the package names\.