Version control messages: what tense?

Solution 1:

Since presumably (1) you're checking in something that you did, and (2) the change has already happened (otherwise you'd have nothing to check in), I'd go with the simple past:

Changed function argument type to int.

If you're checking in a change on behalf of a team, I could also see using:

Function argument type changed to int.

The simple past is the least wordy tense — no helping verbs, no "now"— and is generally the easiest to understand.

I wouldn't suggest using a continuous present or future tense such as "changing", because then the log becomes unclear about what was changed when. _{^{(Akin to the problem of distances in driving directions: when it says "left turn — 5 miles", does that mean the left turn is 5 miles ahead, or do I make a left turn now and then go 5 miles until the next step?)}}

Solution 2:

I think it is up to preference. Personally, I like using imperative: "Change the function argument to int." This especially makes sense if you are using a task management system with task numbers: "Task ID#: 5719 Change the function argument to int." (Or defect numbers, or what have you.) From context you can infer that the task has been completed regardless of verb tense. To indicate partially completed tasks, you can add qualifications such as "Change the function argument to int (partial)" or "Change the function argument to int - 50% complete" or whatever makes sense in your situation.

But definitely check with your colleagues on accepted conventions, unless you're the boss and can tell them what to do. :)

Solution 3:

I think we should differentiate between centralized version control systems, wherein commits are only linear, and decentralized ones.

Assuming a decentralized VCS with a non-linear history

To someone reading a log of comments, each commit begs the question: "What do I change by using this commit?". This is especially true in a scenario wherein one is cherry-picking a changeset from one branch into another. Also, consider if one fetches commits from a remote repository and wants to inspect them first. With this audience in mind, the imperative mood in present tense makes most sense. E.g.:

[Use this commit to] Refactor the User model.

Since this is normally the only context in which I am reading VCS comments, I prefer this style of writing them.

The past tense just seems superfluous to me. Of course each revision has already occurred (in the past), or it would not have been committed yet! The temporal context is unnecessary.

Assuming a centralized VCS with a linear history

In this situation I can see the logic in using the simple past tense, as changes are made completely linearly. However, I think the tense of commit messages becomes a stylistic concern (since the past tense is still assumed). I believe that the current tense, imperative mood scans better (no superfluous "d"s or "ed"s in verbs), but that may simply be a personal preference.

Anyway, I do agree with CJM: I think that consistency is more important than grammar or style points.