diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..67a4c571d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,80 @@ +# Contributing to the AWS Cloud Development Kit Toolkit + +The AWS Cloud Development Kit (AWS CDK) is an open-source software development +framework that you can contribute to. We value community contributions which +significantly impact the development of the AWS CDK. This document will guide +you through learning about contributions, getting started with creating +contributions, and understanding what is required to ensure that your efforts +are impactful and your contribution process goes smoothly. + +Thank you for your interest in contributing to the AWS CDK! We look forward to +working with you to improve the AWS CDK for everyone. ❤️ + +The AWS CDK is released under the [Apache license](http://aws.amazon.com/apache2.0/). +Any code that you submit will be released under that license. + +## Contribution process + +The process of the [aws-cdk Contributing +Guide](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) around finding +items to work and submitting Pull Requests also applies to this repository. This +contributing guide will focus on technical aspects. + +## Prerequisites + +- [Node.js >= 18.18.0](https://nodejs.org/download/release/latest-v18.x/) + - We recommend using a version in [Active LTS](https://nodejs.org/en/about/releases/) +- [Yarn >= 1.19.1, < 2](https://yarnpkg.com/lang/en/docs/install) +- [Docker >= 19.03](https://docs.docker.com/get-docker/) + - the Docker daemon must also be running + +We recommend that you use [Visual Studio Code](https://code.visualstudio.com/) +to work on the CDK. We use `ESLint` to keep our code consistent in terms of +style and reducing defects. We recommend installing the [ESLint +extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) +as well. + +## Getting started + +This is a [projen](https://github.com/projen/projen)-managed repository. After checkout, run the following: + +```shell +$ yarn +$ yarn build +``` + +This will build and unit test all packages. + +## Integration tests + +Integration tests for this package are in a separate repository. They can be found here: + + + +To make a change that involves the integration tests, make sure you have this package checked out. + +Run the tests locally by doing the following: + +```shell +$ cd /path/to/aws-cdk-cli-testing/packages/@aws-cdk-testing/cli-integ +$ bin/run-suite -s ../../../../aws-cdk-cli cli-integ-tests -f 2.179.0 -t 'TEST NAME' +``` + +`-s` points to the root of the `aws-cdk-cli` repository, `-f` is the version of +the framework to use for testing. + +### Submitting a PR that involves changes to integration tests + +When you make a change to both the CLI and the integration tests, you must submit 2 PRs to +the two repositories, and follow the following process: + +0. Initially the integ tests on the `aws-cdk-cli-testing` repository will fail because + the currently published CLI version won't support the new feature yet. +1. Test the changes locally +2. Merge the CLI PR first. +3. Release the CLI. +4. Merge the `aws-cdk-cli-testing` PR. +5. Release the testing PR. + +We will build automation to make this process smoother as soon as possible, but +this is what it is for now. \ No newline at end of file diff --git a/README.md b/README.md index eedbb88b5..3b1b3b3ed 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,64 @@ -# AWS CDK CLI +# AWS Cloud Development Kit (AWS CDK) Toolkit -Command line tools for interacting with AWS CDK applications. +[![NPM version](https://badge.fury.io/js/aws-cdk.svg)](https://badge.fury.io/js/aws-cdk) -> [!NOTE] -> Packages in this repository [used to live](https://github.com/aws/aws-cdk/commit/8b87a637d5ce627ebb23637e853558a9ae545b9f) in the -> main `aws-cdk` repository and were moved here following the decision to split the construct -> library from the CLI. -> -> See [AWS CDK is splitting Construct Library and CLI](https://aws.amazon.com/blogs/opensource/aws-cdk-is-splitting-construct-library-and-cli/) +The **AWS Cloud Development Kit (AWS CDK)** is an open-source software +development framework to define cloud infrastructure in code and provision it +through AWS CloudFormation. -## Packages +The AWS CDK consists of two main components: -The main packages published from this repository are: +- a [class library](https://github.com/aws/aws-cdk), that you use to + to model your infrastructure in code; and +- a *toolkit*, consisting of a CLI or a programmatic library, to act on those + models. -- [`aws-cdk`](https://www.npmjs.com/package/aws-cdk) -- [`cdk-assets@^3`](https://www.npmjs.com/package/cdk-assets) -- [`@aws-cdk/cloud-assembly-schema`](https://www.npmjs.com/package/@aws-cdk/cloud-assembly-schema) +This repository contains the code for the toolkit components. The [class library +repository](https://github.com/aws/aws-cdk) is the main repository for the CDK +project. -## More Information +## Getting Help -Refer to each individual package README for more details. +The best way to interact with our team is through GitHub, on the [aws-cdk +repository](https://github.com/aws/aws-cdk). You can open an +[issue](https://github.com/aws/aws-cdk/issues/new/choose) and choose from one of +our templates for bug reports, feature requests, documentation issues, or +guidance. + +If you have a support plan with AWS Support, you can also create a new [support case](https://console.aws.amazon.com/support/home#/). + +You may also find help on these community resources: + +* Look through the [API Reference](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-construct-library.html) or [Developer Guide](https://docs.aws.amazon.com/cdk/latest/guide) +* The #aws-cdk Slack channel in [cdk.dev](https://cdk.dev) +* Ask a question on [Stack Overflow](https://stackoverflow.com/questions/tagged/aws-cdk) + and tag it with `aws-cdk` + +## Contributing + +We welcome community contributions and pull requests. See +[CONTRIBUTING.md](./CONTRIBUTING.md) for information on how to set up a development +environment and submit code. + +## Structure of this repository + +Here are the packages in this repository. See the README of each package for more information about it: + +| Package | Description | Published? | Maintained? | +|---------|-------------|------------|-------------| +| [aws-cdk](./packages/aws-cdk/) | The CDK Toolkit CLI, main CLI interface to CDK projects. | Yes | +| [cdk](./packages/cdk/) | An alias for `aws-cdk` so you can run `npx cdk` even if it's not installed. | Yes | Yes | +| [cdk-assets v3](./packages/cdk-assets/) | CLI component handling asset uploads, also used as a CLI in [CDK Pipelines](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.pipelines-readme.html) | Yes | Yes | +| [@aws-cdk/cloud-assembly-schema](./packages/@aws-cdk//cloud-assembly-schema/) | The contract between the CDK construct library and the CDK toolkit | Yes | Yes | +| [@aws-cdk/cloudformation-diff](./packages/@aws-cdk/cloudformation-diff/) | CLI component for diffing CloudFormation templates | Yes | Yes | +| [@aws-cdk/cli-lib-alpha](./packages/@aws-cdk/cli-lib-alpha/) | A deprecated attempt at building a programmatic interface for the CLI | Yes | No | +| [@aws-cdk/toolkit-lib](./packages/@aws-cdk/toolkit-lib/) | A work-in-progress programmatic interface for the CLI | No | Yes | +| [@aws-cdk/cli-plugin-contract](./packages/@aws-cdk/cli-plugin-contract/) | TypeScript types for CLI plugins. | No | Yes | +| [@aws-cdk/cdk-cli-wrapper](./packages/@aws-cdk/cdk-cli-wrapper/) | A deprecated attempt at building a programmatic interface for the CLI | No | No | +| [@aws-cdk/node-bundle](./packages/@aws-cdk/node-bundle/) | A tool to build CLI bundles that include license attributions. | No | Yes | +| [@aws-cdk/user-input-gen](./packages/@aws-cdk/user-input-gen/) | A build tool for the CLI and toolkit-lib. | No | Yes | +| [@aws-cdk/yarn-cling](./packages/@aws-cdk/yarn-cling/) | A deprecated build tool for the CLI. | No | No | + +Every package comes with its own unit tests. There is a companion repository to this one containing the integration tests. You can find it here: + +See the [contributing guide](./CONTRIBUTING.md) for more information on this repository.