From 056c149cd9da9aefa22763d8a96f9d19416f5286 Mon Sep 17 00:00:00 2001 From: Elad Ben-Israel Date: Tue, 31 Jul 2018 12:25:29 +0300 Subject: [PATCH 1/2] A few more updates to README * Align phrasing with docs * Fix "License" section * Add "Getting Help" section * Add badges * Shorten installation instructions --- README.md | 106 +++++++++++++++++++++++++++++------------------------- 1 file changed, 57 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index efc47183efaae..907d85ca8328f 100644 --- a/README.md +++ b/README.md @@ -1,76 +1,84 @@ # AWS Cloud Development Kit (AWS CDK) ![Build Status](https://codebuild.us-east-1.amazonaws.com/badges?uuid=eyJlbmNyeXB0ZWREYXRhIjoiRUlEQk1UWVhQRDduSy9iWWtpa012bmJSU0t2aXpCeEtTT2VpWDhlVmxldVU0ZXBoSzRpdTk1cGNNTThUaUtYVU5BMVZnd1ZhT2FTMWZjNkZ0RE5hSlpNPSIsIml2UGFyYW1ldGVyU3BlYyI6IllIUjJNUEZKY3NqYnR6S3EiLCJtYXRlcmlhbFNldFNlcmlhbCI6MX0%3D&branch=master) +[![Version](https://badge.fury.io/js/aws-cdk.svg)](https://badge.fury.io/js/aws-cdk) +[![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.svg)](https://gitter.im/awslabs/aws-cdk) -The **AWS Cloud Development Kit (AWS CDK)** is an infrastructure modeling framework that allows you to define your cloud resources using an imperative programming interface. The CDK is currently in developer preview. We look forward to community feedback and collaboration. +The **AWS Cloud Development Kit (AWS CDK)** is an infrastructure modeling +framework that allows you to define your cloud resources using an imperative +programming interface. The CDK is currently in developer preview. We look +forward to community feedback and collaboration. -Developers can use one of the supported programming languages to define -reusable cloud components called **constructs**, which are composed -together to form **Apps**. Apps are synthesized to AWS -CloudFormation Templates and deployed to the AWS Cloud using the **CDK -Command Line Toolkit**. - -The CDK is shipped with a rich library of constructs called the **AWS -Construct Library**, which includes constructs for all AWS services. - -You will end up writing code that looks like this: - -```ts -const queue = new sqs.Queue(this, 'MyQueue', { - visibilityTimeoutSec: 300 -}); - -const topic = new sns.Topic(this, 'MyTopic'); - -topic.subscribeQueue(queue); -``` - -The following screencast shows the experience of installing and working with the CDK: +[AWS CDK Homepage](https://awslabs.github.io/aws-cdk) | +[Getting Started](https://awslabs.github.io/aws-cdk/getting-started.html) | +[API Docs](https://awslabs.github.io/aws-cdk/reference.html) | +[Getting Help](#getting-help) ![Example usage of CDK](screencast.gif) -## Installation +Developers can use one of the supported programming languages to define reusable +cloud components called [constructs], which are composed together into +[stacks] and [apps]. + +The [AWS CDK Toolkit] is a command-line tool for interacting with +CDK apps. It allows developers to synthesize artifacts such as AWS +CloudFormation Templates, deploy stacks to development AWS accounts and "diff" +against a deployed stack to understand the impact of a code change. -### Prerequisites +The [AWS Construct Library] includes a module for each +AWS service with constructs that offer rich APIs that encapsulate the details of +how to use AWS. The AWS Construct Library aims to reduce the complexity and +glue-logic required when integrating various AWS services to achieve your goals +on AWS. -Make sure you have [Node.js LTS (8.11.x)](https://nodejs.org/en/download) installed. +[constructs]: https://awslabs.github.io/aws-cdk/constructs.html +[stacks]: https://awslabs.github.io/aws-cdk/stack.html +[apps]: https://awslabs.github.io/aws-cdk/apps.html +[AWS CDK Toolkit]: https://awslabs.github.io/aws-cdk/toolkit.html +[AWS Construct Library]: https://awslabs.github.io/aws-cdk/aws-construct-lib.html -### Getting Started +## Getting Started -Install the toolkit, create a demo project in the current directory, and deploy -it: +Install the command-line toolkit from npm (requires [Node.js >= 8.11.x](https://nodejs.org/en/download)): ```shell -npm install -g aws-cdk -cdk init app --language=typescript # or java -npm run build -cdk deploy +npm i -g aws-cdk ``` -### Manual Installation +Initialize an app project in one of the supported languages: -If you prefer to have full control over the installation and version -of the CDK, the complete distribution is also available as a single signed -zip file. +```bash +cdk init app --language=typescript +# or +cdk init app --language=java +# more languages (coming soon)... +``` -[See `MANUAL_INSTALLATION.md` for more information](MANUAL_INSTALLATION.md) +Follow on-screen instructions for next steps. -### Viewing Documentation +> NOTE: The AWS CDK is also available as a single signed zip file. See +[Manual Installation](MANUAL_INSTALLATION.md) for more information. -To view CDK documentation bundled with the release, run: +## Getting Help -```shell -cdk docs -``` +Please use these community resources for getting help. We use the GitHub issues +for tracking bugs and feature requests. -Or view the [online documentation](http://awslabs.github.io/aws-cdk). +* Ask a question on [Stack Overflow](https://stackoverflow.com/questions/tagged/aws-cdk) + and tag it with `aws-sdk-cdk` +* Come join the AWS CDK community on [Gitter](https://gitter.im/awslabs/aws-cdk) +* Open a support ticket with [AWS Support](https://console.aws.amazon.com/support/home#/) +* If it turns out that you may have found a bug, + please open an [issue](https://github.com/awslabs/aws-cdk/issues/new) -## Development +## Contributing -See [CONTRIBUTING](./CONTRIBUTING.md). +We welcome community contributions and pull requests. See +[CONTRIBUTING](./CONTRIBUTING.md) for information on how to set up a development +environment and submit code. -# License +## License -Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. +This AWS CDK is distributed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0). -See [LICENSE](./LICENSE) file for license terms. +See [LICENSE](./LICENSE) and [NOTICE](./NOTICE) for more information. From 1233cf731af86ce080a3ca5dec65e89417f9809c Mon Sep 17 00:00:00 2001 From: Elad Ben-Israel Date: Tue, 31 Jul 2018 12:44:48 +0300 Subject: [PATCH 2/2] Simplify PR template --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- README.md | 36 +++++++++++++++++++++----------- 2 files changed, 25 insertions(+), 13 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 51816d47b3089..c9aaf9b71608b 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1 +1 @@ -By submitting this pull request, I confirm that my contribution is made under the terms of the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) license. +By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license. diff --git a/README.md b/README.md index 907d85ca8328f..8c9bfba81a1e3 100644 --- a/README.md +++ b/README.md @@ -9,9 +9,9 @@ framework that allows you to define your cloud resources using an imperative programming interface. The CDK is currently in developer preview. We look forward to community feedback and collaboration. -[AWS CDK Homepage](https://awslabs.github.io/aws-cdk) | -[Getting Started](https://awslabs.github.io/aws-cdk/getting-started.html) | -[API Docs](https://awslabs.github.io/aws-cdk/reference.html) | +[User Guide] | +[Getting Started] | +[API Reference](https://awslabs.github.io/aws-cdk/reference.html) | [Getting Help](#getting-help) ![Example usage of CDK](screencast.gif) @@ -34,30 +34,42 @@ on AWS. [constructs]: https://awslabs.github.io/aws-cdk/constructs.html [stacks]: https://awslabs.github.io/aws-cdk/stack.html [apps]: https://awslabs.github.io/aws-cdk/apps.html +[User Guide]: https://awslabs.github.io/aws-cdk +[Getting Started]: https://awslabs.github.io/aws-cdk/getting-started.html [AWS CDK Toolkit]: https://awslabs.github.io/aws-cdk/toolkit.html [AWS Construct Library]: https://awslabs.github.io/aws-cdk/aws-construct-lib.html ## Getting Started -Install the command-line toolkit from npm (requires [Node.js >= 8.11.x](https://nodejs.org/en/download)): +* For a detailed walkthrough, see [Getting Started] in the AWS CDK [User Guide] +* See [Manual Installation](./MANUAL_INSTALLATION.md) for installing the CDK from a signed .zip file -```shell -npm i -g aws-cdk +Install the [AWS CDK Toolkit] from npm (requires [Node.js ≥ 8.11.x](https://nodejs.org/en/download)): + +```bash +$ npm i -g aws-cdk ``` -Initialize an app project in one of the supported languages: +Initialize a project: ```bash -cdk init app --language=typescript +$ cdk init app --language=typescript # or -cdk init app --language=java +$ cdk init app --language=java # more languages (coming soon)... ``` -Follow on-screen instructions for next steps. +Use the `cdk` command-line toolkit to interact with your project: + + * `cdk deploy`: deploys your app into an AWS account + * `cdk synth`: synthesizes an AWS CloudFormation template for your app + * `cdk diff`: compares your app with the deployed stack -> NOTE: The AWS CDK is also available as a single signed zip file. See -[Manual Installation](MANUAL_INSTALLATION.md) for more information. +Read the [docs](): + +```bash +$ cdk docs +``` ## Getting Help