Currently the policy for git commits says:

Git commits should:

• Tell a perfect, cleaned up version of the history. As if the code was written perfectly first time.
• Include the MDL-xxxx issue number associated with the change
• Include CODE AREA when appropriate. (Code area, is just a short name for the area of Moodle that this change affects. It can be a component name if that makes sense, but does not have to be. Remember that your audience here is humans not computers, so if a shortened version of a component name is more readable and distinctive, use that instead.)

The problem with this is that it takes up a lot of space in first line of the commit message with metadata, leading to truncated or vague descriptions with the remaining available characters.

For example, on MDL-82372, I am making a change in the qbank_managecategories plugin, to exclude the current category from the list of category options. However, using the prefix for "MDL-82372 qbank_managecategories:" I am only left with about 50% of the characters to express this, and have to result to the vague message "Fix exclusion of current category".

The suggested workaround in the policy is to use a shortened version of the component name. But should this be qbank? managecategories? Would another developer pick the same thing as me? If this is not consistent for a given area, it reduces the value of its inclusion.

Git already includes a feature, trailers, for including metadata in your commits. Using trailers, my commit message could look like this:

Fix exclusion of current category from the category options list

Longer description here....

issue: MDL-82372

component: qbank_managecategories

Trailers can be added with the `--trailer` argument to `git commit`, but form part of the long commit message so can also be added manually.

Trailers are still searched by `--grep` as part of the commit message. For example, I could still do `git log --grep MDL-82372` to see all commits for that issue.

If you want to see this data in the single-line git log, this is achievable by setting the format, for example:

$ git log -1 --format="%(trailers:key=Issue,valueonly,separator= ): %s"

MDL-83272: Fix exclusion of current category from the category options list

Git also has an interpret trailers command for working specifically with trailers.

Since the component would no longer be taking up space in the commit summary, this would also allow us to be more consistent about using the correct name for the component or components that are covered by the commit.