Package: commisery
CommiseryCommisery is a package to help check whether given commit messages adhere toConventional Commits.
Specifically, it checks the syntax and some small aspects of the semantics.The purpose of this is severalfold:Achieving a common layout for commit messages in order to help humans more quickly extract useful information from them.Making these messages partially machine processable in order to classify changes for proper version management.Identifying a subset of common mistakes that render a message useless to your future self or colleagues.The latter goal usually requires your commit messages to answer these questions:What: a short summary ofwhatyou changed in the subject line.Why: what the intended outcome of the change is (arguably themostimportant piece of information that should go into a message).How: if multiple approaches for achieving your goal were available, you also want to explainwhyyou chose the used implementation strategy.Note that you should not explain how your change achieves your goal in your commit message.
That should be obvious from the code itself.
If you cannot achieve that clarity with the used programming language, use comments within the code instead.The commit message is primarily the place for documenting thewhy.Unfortunately, checking whether these last questions get answered is also the most difficult to do automatically.
This tool only checks for a few common errors other than syntax errors:Usage of Jira ticket numbers in the subject line.Because the subject line is expensive real estate every character should be most efficiently used to convey meaning to humans.Jira ticket numbers are not equal to the tickets themselves and thus convey very little information.
These ticket numbers should go in message footers where tools can still extract them for automatic linking.Using non-imperative verb forms (adds, added or adding instead of add) in the subject line.These other forms convey no more meaning but use extra precious characters.Referring to review comments that cannot be found anywhere in the commit history itself.Commit messages should be self-contained.
Only mentioning that a commit is created in response to a review comment, without mentioning the reasoning of that comment is clearly not self-contained.Whenever your workflow permits it, prefer amending the original commit (or using--fixup) instead.If your workflow doesn't permit that, or it seems suboptimal in a given context, describe what, why and how you are changing (as mentioned before).InstallationYou can install this package with pip as follows:pip3install--user--upgradecommiseryUsageYou can verify commit messages with the included CLI tool:$commisery-verify-msg8c3349528888a62382afd056eea058843dfb7690
$commisery-verify-msgmaster
$commisery-verify-msg:/'refactor'$commisery-verify-msg.git/COMMIT_EDITMSG
$commisery-verify-msgmy-own-message.txtThe exit code of that tool will be non-zero if and only if it found errors in the given commit message.After that you can use it as a hook in Git to check messages you wrote by creating a.git/hooks/commit-msgfile with these contents:#!/bin/shexeccommisery-verify-msg"$@"The CLI tool also handles commit-ish revision ranges adhering to thegit rev-listformat:$commisery-verify-msgHEAD~..HEAD
$commisery-verify-msgHEAD^2~4^HEAD^2~6^HEAD^3~2
$commisery-verify-msgmaster..feat/my-feature
$commisery-verify-msgHEAD@{yesterday}..HEAD
$commisery-verify-msgHEAD@{upstream}..HEAD
$commisery-verify-msg:/'refactor'..HEAD
$commisery-verify-msg2fff3d8..8c33495Commisery allows for custom behavior as well:a custom list of accepted Conventional Commit tags can be providedthe presence of a Jira-style ticket reference within the specified commit message (or range) can be enforcedRefer to the built-in help for information on these optional parameters.$commisery-verify-msg--helpGitHub supportYou can use Commisery based on a GitHub PullRequest by installing the package with the extragithub:pip3install--user--upgradecommisery[github]You can verify the Pull Request title and commit messages with the included CLI tool:$commisery-verify-github-pullrequest--tokenGITHUB_TOKEN--repositoryowner/repo--pullrequest-id1The exit code of that tool will be non-zero if and only if it found errors in the given Pull Request.HopicUsing it as a check in Hopic can be accomplished with a configuration fragment like this:phases:style:commit-messages:-python3 -m virtualenv --clear venv-venv/bin/python -m pip install --upgrade 'commisery>=0,<1'# Require each commit message to adhere to our requirements-foreach:AUTOSQUASHED_COMMITsh:venv/bin/python venv/bin/commisery-verify-msg ${AUTOSQUASHED_COMMIT}# Optional: check the produced merge commit message too (this includes the PR title)-venv/bin/python venv/bin/commisery-verify-msg HEADThis exact form can also be used through thecommiserytemplate:phases:style:commit-messages:!template"commisery"