Version control messages: what tense?

Question

In software engineering we use version control systems. Every time we check in modifications we usually leave a message with a summary of change. The question for me has always been: what is the most appropriate and practical tense and form for these messages? Examples:

1. Changed the function argument type to int

2. Function argument type changed to int

3. Function argument type is changed to int

4. Function argument type has been changed to int

5. Function argument type is now int

By "practical" I mean, because most messages are in the same form, they should be succinct, to the point, technical/formal. Best candidate in this regard is probably (2). Sometimes it is tempting to use (5) but you end up flooding your message log with "now", which is not nice. (4) is too long although looks (to me) appropriate in many cases. And finally, (1) and (3) feel wrong somehow, although (1) especially is a widely used one in programming, as far as I can tell.

Any thoughts, suggestions?

Edit: some other forms found by some googling:

1. Change the function argument type to int

2. Changing ...

3. Changes ...

Answer 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?)}}

Answer 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. :)

Answer 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.

Answer 4

In my experience, it doesn't matter how you phrase it, as long as you remain consistent. Clearly, you are recording what actions have happened, so past tense is appropriate.

Speak to your colleagues, and agree on a common approach.

Answer 5

In revision comments, as in any programming comments, the "why" if often more important than the "what," so please permit me to reformulate a bit. If you focus on the action, you might have:

• fixed bug 1234
• fixing bug 1234

But I suggest you focus on the result:

• fixes bug 1234
• fix for bug 1234

As @Alex said in a comment, you first have to decide what you're trying to say. If you're trying to describe the change (thinking of the change as a noun, an entity that the version control system can tell you about) then you want a phrase that characterizes the change itself. For example, if the change was motivated by dissatisfaction that the system limits the user to a single "fooblatz" then the comment might be "allow use of multiple fooblatzes," not "changed data structure to reflect revised fooblatz cardinality."