diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5a1a1dc4f5355..e570c7d5041d0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,39 +7,65 @@ and let us know if it's not up-to-date (even better, submit a PR with your corr ## Pull Requests -1. If there isn't one already, open an issue describing what you intend to contribute. It's useful 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 - * 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. -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`, `refactor(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. - * If this commit includes a breaking change, the commit message must end with a single paragraph - `BREAKING CHANGE: description of what broke and how to achieve this behavior 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, a maintainer will squash-merge to master and will use your PR title/description as the - commit message. +### Step 1: Open Issue + +If there isn't one already, open an issue describing what you intend to contribute. It's useful 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. + +### Step 2: Work your Magic + +Work your magic. Here are some guidelines: + +* Every change requires a unit test +* 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. + +### Step 3: Commit + +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`, `refactor(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. + +* If this commit includes breaking changes, they must be listed at the end in the following format (notice how multiple breaking changes should be formatted): + +``` +BREAKING CHANGE: Description of what broke and how to achieve this behavior now +* Another breaking change +* Yet another breaking change +``` + +### Pull Request + +* Push to a GitHub fork or to a branch (naming convention: `/`) +* Submit a Pull Requests on GitHub and assign the PR for a review to the "awslabs/aws-cdk" team. +* 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. +* 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. + +### Merge + +* Make sure your PR builds successfully (we have CodeBuild setup to automatically build all PRs) +* Once approved and tested, a maintainer will squash-merge to master and will use your PR title/description as the + commit message. ## Design Process