Add Conventional Commit tooling

[jedeen]

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

See also #777

[kamranayub]

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 ***@***.***> 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: <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 — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#1503>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAEJU22QH6SOMR2QX4UVL7TROIAJ5ANCNFSM4MQNUB2Q> .

[kamranayub]

Here it is: https://github.com/zeke/semantic-pull-requests

…

On Fri, Apr 24, 2020, 7:31 PM Kamran Ayub ***@***.***> 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 ***@***.***> 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: > > <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 > > — > You are receiving this because you are subscribed to this thread. > Reply to this email directly, view it on GitHub > <#1503>, or unsubscribe > <https://github.com/notifications/unsubscribe-auth/AAEJU22QH6SOMR2QX4UVL7TROIAJ5ANCNFSM4MQNUB2Q> > . >

[jedeen]

Other options to consider/combine:

• https://github.com/conventional-changelog/commitlint
• https://github.com/conventional-changelog/conventional-changelog
• https://www.npmjs.com/package/semantic-release
• https://www.npmjs.com/package/standard-version

[github-actions]

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

[AndrewCraswell]

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/

1. 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.

2. 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.

3. 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]

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