Finding Problems in Commit Messages and Tickets When Migrating to GitHub

Sometimes, you commit a change, but then you realize that you did not mention the ticket ID in your commit message. Or, worse: you use the wrong ticket ID.

The usual remedy is adding this info to the ticket by hand. On the Agavi Trac, when a ticket ID was incorrect in a commit message, we would typically remove the corresponding entry from the wrong ticket and move it to the correct one.

When migrating to GitHub and replaying all commits and ticket changes, that becomes a problem of course: the commit message still contains text like “fixes #123” when in fact it was supposed to reference ticket #124.

It is therefore necessary to programmatically find and mitigate such problem cases and addressing them before importing things on GitHub. Failure to correct just a single of these problems may break the whole import by having tickets remain open randomly even though they were supposed to be closed and so forth. Here is a list of situations that need to be addressed:

Commit Messages Not Showing Up in Their Tickets

Sometimes a reference to a ticket ID in a commit message does not show up in the corresponding ticket. There are several reasons why this may happen:

1. The message was never supposed to reference a ticket (“Attempt #2 at this stupid merge”) - not a problem in Trac since there is no “refs” or other keyword in front of “#2”, but on GitHub, this commit would show up in ticket #2.
   => Such a commit message must be modified to prevent this situation.
2. The message contains the wrong ticket ID and was removed from that wrong ticket (and inserted by hand on the correct ticket)
   => Such a commit message must be modified to prevent this situation.
3. The Trac post-commit hook was not installed or malfunctioning
   => This usually does not require any action.

Differences in Behavior Between Trac and GitHub

Aside from the first point above, there are other subtle but important differences between how Trac and GitHub parse commit messages:

1. A commit closes several tickets at once without repeating the keyword, e.g. “Add bacon, closes #4 and #5”. This will close both tickets in Trac, but on GitHub, only ticket #4 is closed while ticket #5 is referenced.
   => The commit message must be changed so a “closes” or “fixes” keyword appears before every ticket ID.
2. A commit shows up just fine in the Trac ticket, but the reference would not be detected by GitHub, e.g. due to a missing space character (“This closes #5for real” would close #5 in Trac but do nothing on GitHub).
   => A space character must be inserted
3. A commit closes a ticket that was already closed (this will cause the commit to not show up at all on GitHub).
   => The commit message must be changed, or a reopen command must be sent to the ticket before pushing the second commit.

Human Interference

People do stupid things in their ticket database, so aside from the situation we already discussed where a commit referenced the wrong ticket number, we’ll have to watch out for:

1. A commit referencing a ticket that, at the time the commit was made, did not exist yet (a mistake frequently made by time traveling contributors making commits from the future :>).
   => The easiest fix here is to simply make sure the ticket is created before the commit is pushed.
2. A commit message that shows up in the right (or wrong) ticket, but has been altered (for whatever reason and by whatever means).
   => The commit message must be altered accordingly (or not if that’s not desirable). Optionally, punch the person who fiddled with the message.

Largely Cosmetic Issues

Finally, a few things in commit messages or tickets may not be a problem for the import, but could still be nice to fix:

1. Merges done using svnmerge have the nasty habit of repeating all merged commit messages and thus cluttering the history.
   => It might be nice to remove the clutter from the commit message so all the tickets mentioned in the merged revisions remain clean.
2. A ticket was closed manually, but with a reference to the corresponding commit.
   => This could be fixed by putting the ticket ID into the commit message, which will take advantage of GitHub’s automatic referencing or closing of tickets in such a case.