diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2a5f12c7fed78..f4d94591854be 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,211 +1,190 @@ # Contributing to the AWS Cloud Development Kit +Thanks for your interest in contibuting to the AWS CDK! ❤️ + This document describes how to set up a development environment and submit -contributions to this project. +your contributions. Please read it carefully and let us know if it's not up-to-date (even better, submit a PR with your corrections ;-)). -## Development Workflow +## Pull Requests -1. Setup a [Development Environment](#development-environment) +1. If there isn't one already, open an issue describing what you intend to contribute. It's usful to communicate + in advance, because sometimes, someone is already working in this space, so maybe it's worth + collaborating with them instead of duplicating the efforts. 1. Work your magic. Here are some guidelines: * Every change requires a unit test - * Make sure you update [CHANGELOG] under “[Unreleased]” if the feature/bug is - worthy of a mention - * Make sure to indicate both in the [CHANGELOG] and in the commit message if - the change is BREAKING. A good indication that a change is breaking is if - you had to change old tests to “work” after this change. + * If you change APIs, make sure to update the module's README file * Try to maintain a single feature/bugfix per pull request. It's okay to introduce a little bit of housekeeping changes along the way, but try to avoid conflating multiple features. Eventually all these are going to go into a single commit, so you can use that to frame your scope. -2. Push to a fork or to a branch (naming convention: `/`) -3. Submit a Pull Requests on GitHub. When authoring your pull request - description: - * Think about your code reviewers and what information they need in order to - have fun with your changes. If it's a big commit (hopefully not), try to - provide some good entry points so it will be easier to follow. - * Ideally, associate with an issue (`fixes #`), which describes more - details about motivation and the design process. +1. Create a commit with the proposed change changes: + * Commit title and message (and PR title and description) must adhere to [conventionalcommits]. + * The title must begin with `feat(module): title`, `fix(module): title`, + `reactor(module): title` or `chore(module): title`. + * Title should be lowercase. + * No period at the end of the title. + * Commit message should describe _motivation_. Think about your code reviewers and what + information they need in order to understand what you did. If it's a big commit (hopefully not), + try to provide some good entry points so it will be easier to follow. + * Commit message should indicate which issues are fixed: `fixes #` or `closes #`. * Shout out to collaborators. * If not obvious (i.e. from unit tests), describe how you verified that your change works. -4. Assign the PR for a review to the "awslabs/aws-cdk" team. + * If this commit includes a breaking change, the commit message must end with a + a single pragraph + `BREAKING CHANGE: description of what broke and how to achieve this beahvior now`. +2. Push to a fork or to a branch (naming convention: `/`) +3. Submit a Pull Requests on GitHub and assign the PR for a review to the "awslabs/aws-cdk" team. 5. Discuss review comments and iterate until you get at least one “Approve”. When iterating, push new commits to the same branch. Usually all these are going to be squashed when you merge to master. The commit messages should be hints for you when you finalize your merge commit message. +7. Make sure to update the PR title/description if things change. The PR title/description are going + to be used as the commit title/message and will appear in the CHANGELOG, so maintain them all + the way throughout the process. 6. Make sure your PR builds successfully (we have CodeBuild setup to automatically build all PRs) -7. Once approved and tested, squash-merge to master __via GitHub__. This is your - opportunity to author a beautiful commit message which describes __the - motivation__ and __design considerations__ of your change. Here are some - [tips](https://chris.beams.io/posts/git-commit/#separate) from Chris Beams. +7. Once approved and tested, a maintainer will squash-merge to master and will use your PR + title/description as the commit message. -## Development Environment +## Tools -This is a monorepo which uses [lerna](https://github.com/lerna/lerna). +The CDK is a big project, and, at the moment, all of the CDK modules are mastered in a single monolithic +repository (uses [lerna](https://github.com/lerna/lerna)). There are pros and cons to this approach, +and it's especially valuable to maintain integrity in the early stage of thr project where things constantly change across the stack. In the future we believe many of these modules will be extracted to their own repositories. -The CDK depends on [jsii](https://github.com/awslabs/jsii), which is still not -published to npm. Therefore, the jsii tarballs are checked-in to this repository -under `./local-npm` and the install script will install them in the repo-global -`node_modules` directory. +Another complexity is that the CDK is packaged using [jsii](https://github.com/awslabs/jsii) to multiple +programming languages. This means that when a full build is complete, there will be a version of each +module for each supported language. -### Prerequisites +However, in many cases, you can probably get away with just building a portion of the +project, based on areas that you want to work on. -Since this repo produces artifacts for multiple programming languages using -__jsii__, it relies on the following toolchains: +### Main build scripts - - [Node.js 8.11.0](https://nodejs.org/download/release/v8.11.0/) - - [Java OpenJDK 8](http://openjdk.java.net/install/) - - [.NET Core 2.0](https://www.microsoft.com/net/download) - - [Python 3.6.5](https://www.python.org/downloads/release/python-365/) - - [Ruby 2.5.1](https://www.ruby-lang.org/en/news/2018/03/28/ruby-2-5-1-released/) +The build process is divided into stages, so you can invoke them as needed: -When building on CodeBuild, these toolchains are all included in the -[superchain](https://github.com/awslabs/superchain) docker image. This image can -also be used locally as follows: +- __`install.sh`__: installs all external dependencies and symlinks internal dependencies (using `lerna link`). +- __`build.sh`__: runs `npm build` and `npm test` in all modules (in topological order). +- __`pack.sh`__: packages all modules to all supported languages and produces a `dist/` directory + with all the outputs (running this script requires that you installed the [toolchains](#Toolchains) + for all target languages on your system). -```shell -eval $(aws ecr get-login --no-include-email) -IMAGE=260708760616.dkr.ecr.us-east-1.amazonaws.com/superchain:latest -docker pull ${IMAGE} -docker run --net=host -it -v $PWD:$PWD -w $PWD ${IMAGE} -``` - -This will get you into an interactive docker shell. You can then run -`./install.sh` and `./build.sh` as described below. - -Also install the [git-secrets](https://github.com/awslabs/git-secrets) tool -and activate it on your working copy of the `aws-cdk` repository. +### Partial build tools -### Bootstrapping +There are also two useful scripts in the `scripts` directory that can help you build part of the repo: -1. Clone this repository (or run `git clean -fdx` to clean up all build artifacts). -2. Run `./install.sh` - this will install all repo-level dependencies, including - `lerna` and the unpublished modules from local-npm. -3. Run `./build.sh` - this will invoke `lerna bootstrap` and `lerna run test`. - All external dependencies will be installed and internal deps will be - cross-linked. +- __`scripts/buildup`__: builds the current module and all of it's dependencies (in topological order). +- __`scripts/builddown`__: builds the current module and all of it's consumers (in topological order). -### buildup/builddown +### Useful aliases -If you only want to work on a subset of the repo, you can use `scripts/buildup` and -`scripts/builddown` to build a package and all it's dependencies (up) or -dependents (down). +You can also add a few useful aliases to your shell profile: -Make sure to run `./install.sh` from the root to make sure all modules are installed. - -It is useful to add the `./scripts` directory to your PATH. - -Then, change the working directory to any package in the repo and run: +```bash +# runs an npm script via lerna for a the current module +alias lr='lerna run --stream --scope $(node -p "require(\"./package.json\").name")' - buildup # will also build all dependencies +# runs "npm run build" (build + test) for the current module +alias lb='lr build' +alias lt='lr test' -Or: +# runs "npm run watch" for the current module (recommended to run in a separate terminal session): +alias lw='lr watch' +``` - builddown # will also build all consumers +### pkglint -### Development Iteration +The `pkglint` tool "lints" package.json files across the repo according +to [rules.ts](tools/pkglint/lib/rules.ts). -After you've bootstrapped the repo, you would probably want to work on individual packages. +To evaluate (and attempt to fix) all package linting issues in the repo, run the following command from the root +of the repository (after boostrapping): -All packages in the repo have a two useful scripts: `prepare` and `watch`. In order to execute -these scripts, use `lerna run --stream --scope