Add Conventional Commit tooling

jedeen commented 4 years ago

Context

Currently, we have guidelines for how to format commit message in general, but do not have enforced standards for how to add commit metadata (is this a breaking change, is this a bugfix, other changes adjacent to semantic versioning concerns, etc.) We stopgap some of that with Github labels, but those do not exist in the Git commit history.

Proposal

enforce the Conventional Commit format for all commits that are merged to the main branch
- this will allow us to automatically determine the appropriate semantic version for post-1.0 releases of Excalibur
add optional linting command for developers to use locally
- this prevents having to require that community contributors follow the strict commit message format, since we squash and rebase all pull requests when merging
automate changelog updates on pull request merge
- if commit messages are required to be well-formatted and provide proper context, then the vast majority of the changelog can be automated
maintain the majority of our git commit message format conventions, as described in our Contributing document
update the Contributing document to include the new Conventional Commits formatting guidelines

Commit Format Examples

General template:

<type>[optional scope]: <Description>

[optional body]

closes #issue_number

Specific example:

fix: Prevent sounds from playing when the game is stopped

Ensure all sounds stop when the game is stopped, and Sound.play() does not play sounds when the game is stopped

closes #1476

additional info: https://www.conventionalcommits.org

kamranayub commented 4 years ago

We use a GitHub app called Semantic Merge I think that ensures PR titles are consistent with CC and then can auto merge them. This would be great!

On Fri, Apr 24, 2020, 4:31 PM jedeen notifications@github.com wrote:

Context

Currently, we have guidelines for how to format commit message in general, but do not have enforced standards for how to add commit metadata (is this a breaking change, is this a bugfix, other changes adjacent to semantic versioning concerns, etc.) We stopgap some of that with Github labels, but those do not exist in the Git commit history. Proposal

enforce the Conventional Commit format for all commits that are merged to the main branch

this will allow us to automatically determine the appropriate semantic version for post-1.0 releases of Excalibur

add linting command for developers to use locally (if they wish)

this prevents having to require that community contributors follow the strict commit message format, since we squash and rebase all pull requests

automate changelog updates on pull request merge

if commit messages are required to be well-formatted and provide proper context, then the vast majority of the changelog can be automated

maintain the majority of our git commit message format conventions, as described in our Contributing document

Commit Format Examples

General template:
[optional scope]: [optional body] closes #issue_number Specific example: fix: Prevent sounds from playing when the game is stopped Ensure all sounds stop when the game is stopped, and Sound.play() does not play sounds when the game is stopped closes #1476 additional info: https://www.conventionalcommits.org — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub , or unsubscribe .

kamranayub commented 4 years ago

Here it is:

https://github.com/zeke/semantic-pull-requests

On Fri, Apr 24, 2020, 7:31 PM Kamran Ayub kamran.ayub@gmail.com wrote:

We use a GitHub app called Semantic Merge I think that ensures PR titles are consistent with CC and then can auto merge them. This would be great!

On Fri, Apr 24, 2020, 4:31 PM jedeen notifications@github.com wrote:

Context

Currently, we have guidelines for how to format commit message in general, but do not have enforced standards for how to add commit metadata (is this a breaking change, is this a bugfix, other changes adjacent to semantic versioning concerns, etc.) We stopgap some of that with Github labels, but those do not exist in the Git commit history. Proposal

enforce the Conventional Commit format for all commits that are merged to the main branch

this will allow us to automatically determine the appropriate semantic version for post-1.0 releases of Excalibur

add linting command for developers to use locally (if they wish)

this prevents having to require that community contributors follow the strict commit message format, since we squash and rebase all pull requests

automate changelog updates on pull request merge

if commit messages are required to be well-formatted and provide proper context, then the vast majority of the changelog can be automated

maintain the majority of our git commit message format conventions, as described in our Contributing document

Commit Format Examples

General template:
[optional scope]: [optional body] closes #issue_number Specific example: fix: Prevent sounds from playing when the game is stopped Ensure all sounds stop when the game is stopped, and Sound.play() does not play sounds when the game is stopped closes #1476 additional info: https://www.conventionalcommits.org — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub , or unsubscribe .

jedeen commented 4 years ago

Other options to consider/combine:

github-actions[bot] commented 3 years ago

This issue hasn't had any recent activity lately and is being marked as stale automatically.

AndrewCraswell commented 3 years ago

Perhaps worth mentioning an alternative for those who don't want the chore of enforcing and abiding by conventional commit standards. Beachball JS was developed and is used extensively throughout Microsoft. It's an alternative to Conventional Commits that solves the same problems in a more streamlined way without relying on commit messages. Only mentioning it because our projects recently shifted over, and we found it reduced a lot of friction and need for compliance verification. I think this ticks all the checkboxes described in the issue.

https://microsoft.github.io/beachball/

When a dev commits a change, they must create a change file. This is done automatically for you by executing beachball change. This initiates a quick series of questions -- it automatically determines which packages were modified (in the case of a monorepo) and asks what kind of change was made (patch, minor, major, etc) with a clear definition of each change to help new contributors. Finally you add a quick description of the change, or can select from the last few commit messages. This generates a change json file, which is checked in automatically.
A post-push git hook can validate that change files were generated using the beachball check command. If not the push can be denied and a descriptive error shown to guide new contributors. This can also be done during CI to be sure all commits are mapped to a change file before merging into the master branch.
During the CD pipeline, the beachball publish command initiates a review of all change files. Based on the changes and their types, it chooses the proper semver value, and updates the packages and auto-generates new changelog histories. These are committed back to the branch automatically, and the change files themselves are deleted. The publish command automatically initiates an npm publish of any packages that were modified.

github-actions[bot] commented 3 years ago

This issue hasn't had any recent activity lately and is being marked as stale automatically.

github-actions[bot] commented 4 weeks ago

This issue hasn't had any recent activity lately and is being marked as stale automatically.

excaliburjs / Excalibur