CVSspam Documentation

1.2.1. Simple Installation

Pick a location for the three scripts to live, such as /usr/local/lib/cvsspam/. Copy the scripts here, and confirm that the files are executable:

$ /usr/local/lib/cvsspam/cvsspam.rb
missing required file argument
Usage: cvsspam.rb [ --to <email> ] [ --config <file> ] <collect_diffs file>

Copy the example cvsspam.conf to /etc/cvsspam.

1.2.2. Installation Using CVS

Check out your repository's CVSROOT.

...set $CVSROOT to point at your repository...
$ cvs checkout CVSROOT
$ cd CVSROOT
$ ls
CVS           commitinfo  cvswrappers  loginfo  notify   taginfo
checkoutlist  config      editinfo     modules  rcsinfo  verifymsg

Place record_last_dir.rb, collect_diffs.rb and cvsspam.rb into this directory.

Add these three filenames into CVSROOT/checkoutlist

# The "checkoutlist" file is used to support additional version controlled
# administrative files in $CVSROOT/CVSROOT, such as template files.
#
# The first entry on a line is a filename which will be checked out from
# the corresponding RCS file in the $CVSROOT/CVSROOT directory.
# The remainder of the line is an error message to use if the file cannot
# be checked out.
#
# File format:
#
#       [<whitespace>]<filename><whitespace><error message><end-of-line>
#
# comment lines begin with '#'
record_lastdir.rb
collect_diffs.rb
cvsspam.rb

cvs add the three scripts to the repository, then cvs commit them, and the modified checkoutlist.

In commitinfo and loginfo you can now refer to the scripts with $CVSROOT/CVSROOT/record_lastdir.rb and $CVSROOT/CVSROOT/collect_diffs.rb

1.5.1. Sendmail / SMTP

By default, CVSspam will attempt invoke an external program to send out messages. This program will normally be /usr/sbin/sendmail, but you can specify another using the $sendmail_prog setting in the config file. (Whatever you specify must accept the email on it's stdin, and understand the '-t' flag to cause it to take message headers from this input.)

By specifying $smtphost in the configuration file, you can make CVSspam contact an SMTP server directly, rather than using an external program. Only use this option if there is no MTA installed on your CVS server.

$smtphost = "mail.example.domain"

1.5.2. From Address

When all CVS users have real accounts on the server, the sender address in generated emails will be derived from the username of the commiter. This relies on a standard behavior of sendmail-like MTAs; we don't specify any address, so the MTA must add one.

CVS accounts are commonly aliased to a less privileged account on the server, such as 'nobody', for extra security. Unfortunately, combined with the default CVSspam configuration, this will result in all notifications appearing to originate From 'nobody@hostname', obscuring the actual commiter.

CVSspam provides a --from option which you can use to specify the person who is really committing. Further, CVS provides a magic $USER keyword in the loginfo file that will be replaced with the CVS account name.

# loginfo entry for aliased accounts
^myproject /path/to/collect_diffs.rb --from $USER --to me@somewhere.invalid %{sVv}

If you would like control over the email address used for each user, consider using a platform-specific meachanism for customising how your MTA formats user's addresses (e.g. /etc/email-addresses). Additionally, CVSspam will make use of CVSROOT/users, if this exists, to derive the email address. The format of CVSROOT/users is one username:address pair on each line (as documented in Open Source Development with CVS)

1.5.3. Global Email Addresses

Recipient email addresses can be put in the configuration file as well as in each loginfo entry. For example,

addRecipient "code-review@somewhere.invalid"
addRecipient "project-owner@somewhere.invalid"

2.1.1. Bugzilla

For Bugzilla, when a CVS log comment contains text like Fix for bug 123..., the text "bug nnn" will become a hyper-link to that Bugzilla page in the generated email.

To enable, give your Bugzilla's URL in CVSspam's configuration file

$bugzillaURL = "http://bugzilla.mozilla.org/show_bug.cgi?id=%s"

2.1.2. JIRA

For JIRA, include the issueId in the log comment. JIRA issue Ids have a project name and issue number, separated by a dash. For example JRA-1545.

To enable, give your JIRA installation's URL in CVSspam's configuration file

$jiraURL = "http://jira.atlassian.com/secure/ViewIssue.jspa?key=%s"

2.1.3. RT

For systems that like to talk about tickets, CVSspam will make links from text in the log comment that looks like "ticket nnn" (where nnn is a number). For instance with RT, supply the location of Display.html

$ticketURL = "http://localhost/rt2/Ticket/Display.html?id=%s"

2.2.1. ViewCVS

To enable ViewCVS support, specify the URL of the top-level ViewCVS directory in cvsspam.conf.

$viewcvsURL = "http://localhost/cgi-bin/viewcvs.cgi/"

2.2.2. CVSweb

For CVSweb, specify the URL of cvsweb.cgi,

$cvswebURL = "http://localhost/cgi/cvsweb.cgi/"

2.2.3. Chora

For Chora, specify the URL of the directory containing cvs.php,

$choraURL = "http://localhost/hord/chora/"

2.2.4. Multiple CVS repositories

If ViewCVS or CVSweb are configured for multiple repositories, you can specify which to use by defining a value for $repository_name. You can either hardcode the name of a repository, or use the special value GUESS, which will cause CVSspam to use the last segment of the CVSROOT path as the repository name.

# this is the top-secret repository
$repository_name = "Secret Projects"

Note that GUESS is not surrounded by quotes.

# our repositories are named after their containing directories,
$repository_name = GUESS

GUESS should be handy in environments like GForge