For the sake of this question, let’s agree on this definition of “good commit message” from here:
Your comment should be brief and to the point, describing what was changed and possibly why.
and accept that referencing a bug/issue in a commit message is a good thing.
Now, there are a lot of tools that integrate with VCS repositories and, for them to function, require commit messages to contain various “control information” which generally does not add value in the historical sense? Think,
- Amount of time spent fixing an issue (
[Spent: 4h])
- A /cc to notify other team members of the changeset (
/cc john, jill)
- A tag to the CI server to deploy the changeset to development/staging/production (
[deploy: production])
- Setting a reviewer (
R: jill)
Granted, this is all very convenient for developers in the short term (why leave console to push a button in the CI interface when I can add a short string to commit message), but I find these messages to clutter changelog too much and way too infrastructure-specific (what if we change to a Time Tracker which uses slightly different syntax?).
What’s your take on these messages and where do you draw the line on what to accept and what to forbid?
Infrastructure-related additions in commit comments
For the sake of this question, let’s agree on this definition of “good commit message” from here:
and accept that referencing a bug/issue in a commit message is a good thing.
Now, there are a lot of tools that integrate with VCS repositories and, for them to function, require commit messages to contain various “control information” which generally does not add value in the historical sense? Think,
[Spent: 4h])/cc john, jill)[deploy: production])R: jill)Granted, this is all very convenient for developers in the short term (why leave console to push a button in the CI interface when I can add a short string to commit message), but I find these messages to clutter changelog too much and way too infrastructure-specific (what if we change to a Time Tracker which uses slightly different syntax?).
What’s your take on these messages and where do you draw the line on what to accept and what to forbid?
Those should not be part of the commit message, they should be attached to the commit as metadata. See git notes for example, which allow you to attach arbitrary metadata to any Git object, including blobs, trees, commits, annotated tags, signed tags, and even notes (which would make this metametadata, I guess). Other version control systems have similar capabilities.
If the messages are compact and standardized enough for some tool to parse and act on them, then they are compact and standardized enough for another tool or plug-in to detect them when you want to read the purely technical stream of development. In other words, you should keep the messages and educate your VCS log viewer to filter them out.
Filed under: softwareengineering - @ 18:09
Thẻ: comments, version-control
« Documenting the effect of std::move ⇐ More Pages ⇒ Infrastructure-related additions in commit comments »