www.jrgns.net

I'm start work with a new company in October, and one of my duties will be to start up some kind of source repository. Yup, it's scary, there's still companies out there with no kind of source control. Anyway, I started thinking about how the log entries made when committing to the source repo can be helpful.

Some things to keep in mind:

Someone else will have to read this

If your collaborating on a project, someone other than you will have to read the log entries, and try to figure out what you did. Phrases like "Fixed that bug" is totally meaningless and frustrating, so be verbose without raning. The code maintainers don't want to know that you made that change in the nude. My detailed longterm memory is totally bust, so I have to be verbose or I won't understand my own entries in a month's time...

Use the log as a logging system

It's quite easy to compile a changelog from your source code repository's log if the developers logged what they actually did. If you added some new functionality, write it down, if you changed over from one library to another, say so! If you worked on a specific bug, mention the bug number or reference as well. This kind of forces you to regularly document your changes, making maintaining code and reporting on your work much easier in the long run.

Tag the changes

By giving the log entry some kind of context, you greatly increase the value of the entry. If it's part of a certain development or debugging drive, just put in a line saying so. You can also mention the state of the project, be it Beta or Release Candidate. This gives whoever is reading the log an idea of where in the development this change happened.

Keep it neat

For my own system, I try to keep to the Markdown syntax, as it makes the text easier to read, and, if you want to, you can quite easily export the log entries to HTML.

An example:

####Standard Maintenance
+ Started work on converting to Smarty templating, needs work
+ Fixed bugs #232 and #234

**Mostyle Stable**