chore: how to format multiple breaking changes in commit messages (#2179

)

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 #<issue>` or `closes #<issue>`.
- * 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: `<user>/<feature-bug-name>`)
-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 #<issue>` or `closes #<issue>`.
+
+* 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: `<user>/<feature-bug-name>`)
+* 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