HTCondorWiki: Commit Messages

Page History

A good commit message makes reviewing your changes later easier, and is especially helpful when the release wrangler is ensuring that the version history is complete.

A commit message should have:

The GitTrac ticket number, in the form #123. Note that you cannot have a "#" at the start of a line; Git will think it's a comment. Common techniques include putting the comment at the end of the line, or enclosing it in parenthesis like (#123). If multiple tickets are involved, feel free to list them all. If zero tickets are involved, consider creating a ticket so people have a place to discuss the change and a convenient place to point to for all relevant information.
- Why? This number makes correlating the version history easier (assuming you include the ticket number in a comment in the version history like you should). It also means that the ticket can include links to the relevant commits.
A brief description of what you changed.
Optionally, some extended discussion on what you changed, if you think it useful.
Finally, if you are confident that this change should not be mentioned in the version history, a brief note explaining why. Is it entirely invisible to the user (internal cleanup)? Does it fix a bug that was never released?

Finally, remember to update the Version History! VersionHistoryHowTo

Git help for tickets

You may be absent-minded, and everyone occasionally forgets to put ticket numbers in their commit message. Git will actually help with this. You can run the following commands:

git config --global commit.template ~/.gittemplate

Then, edit your ~/.gittemplate file to look like the following:

The ticket is #xxxx

This template will be included in your commit message every time you run "git commit", and reminds you to write a ticket number.

Sometimes you will be in a hurry, and rush over the ticket number above. For this situation, you can install the following executable script at <path-to-CONDOR_SRC>/.git/hooks/commit-msg:

#!/bin/sh
#
# An example hook script to check the commit log message.
# Called by git-commit with one argument, the name of the file
# that has the commit message.  The hook should exit with non-zero
# status after issuing an appropriate message if it wants to stop the
# commit.  The hook is allowed to edit the commit message file.

/bin/grep -E -q '\#[0-9]+' "$1" || {
        echo
        echo
        echo "****** YOUR COMMIT WAS NOT ACCEPTED ******"
        echo "You need to assign a ticket number"
        echo
        echo
        exit 1
}

So now git will remind you loudly and refuse to commit if you forget to include a ticket number. If you are really sure that a ticket is not needed, you can override this with the command git commit --no-verify.