ChangeLog

This page is for people who have commit access to the bundles repository.

Committing Files

You generally want to commit only one change at a time. If the change affects multiple files, you should commit all involved files at once.

The reason why you want to do one commit per change is twofold:

  1. If a change is bad, it is much easier to revert, if the commit only had that one change.

  2. If someone does svn blame to figure out why something was changed, and the corresponding commit message lists half a dozen changes, it is almost of no help at all.

Writing Commit Entries

Even though most bundle items are short, try to be as detailed as possible about why you are making the change. If you are making a change to fix an edge case, put an example of the edge case in the commit log.

Consider that in a year someone other than you will have to fix something in the same item, he may question your change, or your change may break some other edge case. It should be possible to get the full picture from the commit log, as to why the change was made, otherwise there is a chance the problem it fixed might be re-introduced, because someone did not understand why you made your change.

So bottom line: it is generally better to explain why you are making a change than what you are actually changing.

Referencing Tickets

Although the ticket system should not be used to report problem with bundle items, it occasionally happens.

If you make a commit in response to a ticket be sure to put the ticket number in the commit message and prefix it with ticket. For example: ticket A717D84D.

This has three advantages:

  1. The ticket number will be a link to the ticket in the RSS feed.

  2. If the commit message ends up in the TextMate release notes (see Magic Tags) then the ticket is automatically closed, when the fix is in latest TextMate build.

  3. If someone later stumbles upon the changes done, e.g. via svn blame and requests the log entry for that change, the referenced ticket will often give more info, as to why the change was necessary.

Magic Tags

You can prefix a line in a commit entry with a magic tag. There are 3 magic tags described in the forthcoming sections.

Prefixing a line will cause that line to be reported in the TextMate release notes. It will prefix the line with the bundle name and put your name (in parenthesis) after the entry. Only the physical line with the tag, will be reported.

Be aware though that generally you should not prefix your lines with these magic tags. Only for bundles included by default, or when adding a new bundle to the repository, should they be used, and only about things that matters, read on for what matters.

[NEW]

Some new cool functionality was added to a (default) bundle. That would for example be code completion for Cocoa, or a similar feature which is newsworthy, but adding a snippet or a new rule to a language grammar is not newsworthy.

I.e. use this about functionality where the user will think “oh, I gotta check out that” but not something the user would likely stumble upon himself, or not really care about.

As a rule of thumb, language grammar changes, snippets, and preferences generally never give rise to a [NEW] tag.

[CHANGED]

Something was changed. Use this only for changes which may surprise the user but aren't easy for the user to adapt to themselves.

For example changing all the HTML snippets to not end with a slash, and instead require the user to set the TM_XHTML variable, if he wants the slash, does require the corresponding commit to have a [CHANGED] tag, because many users will be surprised by the apparent missing slash, and they might not find the solution easily.

A rule of thumb is: could the user be frustrated or react with surprise or dismay by your change. Will they imagine that something has been broken. Might they write a support ticket to "fix" your change. Does the change require the user to take some action before getting the feature to work again, like changing a command to read some user configuration from another place than previously. These are all instances where the [CHANGED] tag would be required.

[FIXED]

Something got fixed. This is rarely needed, but if a bundle item was the cause of a serious problem, for example a language grammar caused an infinite loop, and users were reporting this, it might be a good idea to put [FIXED] in the commit message, so users will see that they can now safely use the item again.

Also problems which have a corresponding ticket can use the [FIXED] tag, this is really just a convenience to have the ticket automatically closed.

See Also

Peter Hutterer has this post on commit messages.