commit message building blocks

commit-message-toolbox.md

• Why?

  • describe issue (motivation of the change)
    • describe error scenario ("as-is it throws unhandled exception on special characters").
    • introduce issue report (i.e. cite linter warnings)
    • describe shortcomings ("I'm unhappy with [...]: No timeouts, features like x are clumsy.")
  • illustrate requirement
    • usage need ("x is only works on pre-Python 3.7, but we want to support all Python 3 versions")
    • out of date ("remove outdated property. x is no longer defined, but was still referenced in the docs")
    • runtime or dev env change ("API has changed, fixing the example")
  • describe objective
    • to fix defects ("Fix concurrency problem, ...")
    • to make improvements (functional/non-functional goals, i.e. "Added x to to y")
  • imply necessity
    • conventions and standards ("it is common to add tests to the same package as the class under test")
    • relation to prior changes/commits ("the code was changed by commit x, but the test was not part of it")
    • relation to an implemented feature ("a short step towards x"; "will make a future change easier")
    • improvements and benefits ("Use x. Since we omit y, this more clearly does z.")

• What?

  • summarize code object change
    • object of change ("remove creation of 'fat' jar")
    • contrast before and after ("rename x to y")
    • characteristics of changes (summary of the diff)
    • change list ("this marks the following properties as deprecated: x,y,z")
  • illustrate function ("rename property x so it's clear that...")
  • describe implementation principle (technical principle underpinning the change, "w uses x to get y. On macOS, x returns z."

• no why for:

  • test cases
  • typo fixes
  • text file changes
  • annotation changes
  • code refactoring
  • version management

source: https://arxiv.org/pdf/2202.02974.pdf