Repository Commit Msg Etiquette

I've never had the chance to work with a team on a repo, so I'm wondering if there is a proper way to document your changes.

For example, maybe add a tag(s) such as: bugfix, update, implement? Just curious on how professionals describe their com开发者_运维百科mits.

Hopefully it'll aid me in keeping the project organized...

---

It should be a clear, concise description of what was changed or implemented in that commit. If you've integrated with an issue tracking system, the issue number is also useful.

The bottom line is, the message should make sense to a) other people, so that they understand what was done without looking at the code, and b) yourself, when you look at the log a year later trying to find where you fixed the bug with the foobar.

Example of a good message:

Fixed the bug where the program would crash if the number of entries was zero
(issue #2857)

Example of a bad message:

Fixed email bug

---

Commit comments should contains a brief description of what you did and why you did it, without details on the how: if someone needs this kind of details, he can look the diffs. Don't fill the comments with redundant implementation details.

---

There are very different approaches to this, some people don't even use commit messages but commit a ChangeLog file along with the rest (I wouldn't recommend it though, it's pain to merge all the time). I agree with Michael all the way, just wanted to point out that different environments are more or less helpful when it comes to commit messages, for example git has a certain preference what messages should look like.

If you're using trac for example, it'll help you to put the ticket number in there with a certain syntax (e.g. #1234, at least i think it is), which will cause it to show up as a hyperlink when viewed in trac's timeline.

---

As verbose as possible is always the best idea.

Also make sure to Comment Branches, Tags and Merges, correctly. It will save you headaches.

i.e. MERGE: [from location] [Start repo #] : [end repo #] - [additional comments]