GNU Info

(cvsbook.info)Log Messages And Commit Emails

---

Next: Changing A Log Message After Commit Prev: Watches (CVS As Telephone) Up: Advanced CVS

---

Enter node , (file) or (file)node

Log Messages And Commit Emails
==============================

Commit emails are notices sent out at commit time, showing the log
message and files involved in the commit.  They usually go to all
project participants and sometimes to other interested parties.  The
details of setting up commit emails were covered in Note: Repository
Administration, so I won't repeat them here.  I have noticed, however,
that commit emails can sometimes result in unexpected side effects to
projects, effects that you may want to take into account if you set up
commit emails for your project.

First, be prepared for the messages to be mostly ignored.  Whether
people read them depends, at least partly, on the frequency of commits
in your project.  Do developers tend to commit one big change at the end
of the day, or many small changes throughout the day?  The closer your
project is to the latter, the thicker the barrage of tiny commit notices
raining down on the developers all day long, and the less inclined they
will be to pay attention to each message.

This doesn't mean the notices aren't useful, just that you shouldn't
count on every person reading every message.  It's still a convenient
way for people to keep tabs on who's doing what (without the
intrusiveness of watches).  When the emails go to a publicly
subscribable mailing list, they are a wonderful mechanism for giving
interested users (and future developers!) a chance to see what happens
in the code on a daily basis.

You may want to consider having a designated developer who watches all
log messages and has an overview of activity across the entire project
(of course, a good project leader will probably be doing this anyway).
If there are clear divisions of responsibility - say, certain
developers are "in charge of" certain subdirectories of the project -
you could do some fancy scripting in CVSROOT/loginfo to see that each
responsible party receives specially marked notices of changes made in
their area.  This will help ensure that the developers will at least
read the email that pertains to their subdirectories.

A more interesting side effect happens when commit emails aren't
ignored.  People start to use them as a realtime communications method.
Here's the kind of log message that can result:

     Finished feedback form; fixed the fonts and background colors on the
     home page.  Whew!  Anyone want to go to Mon Lung for lunch?

There's nothing wrong with this, and it makes the logs more fun to read
over later.  However, people need to be aware that log messages, such as
the following, are not only distributed by email but is also preserved
forever in the project's history.  For example, griping about customer
specifications is a frequent pastime among programmers; it's not hard to
imagine someone committing a log message like this one, knowing that the
other programmers will soon see it in their email:

     Truncate four-digit years to two-digits in input.  What the customer
     wants, the customer gets, no matter how silly & wrong.  Sigh.

This makes for an amusing email, but what happens if the customer
reviews the logs someday?  (I'll bet similar concerns have led more than
one site to set up CVSROOT/loginfo so that it invokes scripts to guard
against offensive words in log messages!)

The overall effect of commit emails seems to be that people become less
willing to write short or obscure log messages, which is probably a good
thing.  However, they may need to be reminded that their audience is
anyone who might ever read the logs, not just the people receiving
commit emails.