chore: expand README and start Contributing Guide

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:
+
+<https://github.com/aws/aws-cdk-cli-testing>
+
+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.

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: <https://github.com/aws/aws-cdk-cli-testing>
+
+See the [contributing guide](./CONTRIBUTING.md) for more information on this repository.