• CvsNotify

1. Introduction
2. Changes
3. Features
4. Similar Programs
5. Platforms
6. License
7. Support
8. Credits
9. More Information
10. Activity Batching
11. Sample Email Message
12. Known Issues
13. Troubleshooting
14. Installation
15. Which Version is Installed?
16. Installing on non-Windows Platforms
17. Windows Installation
18. Installation Part 1: Customization
    1. Testing Email Settings
    2. Testing IRC Settings
19. Installation Part 2: Running the dgcvsnotify daemon
20. Installation Part 3: Configuring the CVS Server
    1. CVS Users File
21. Installation Part 4: Advanced Customization
22. Stopping IRC Output
23. Modifying Source Code on Windows Platforms
24. PerlApp Support

Introduction

CvsNotify is a program for CVS that sends "taginfo", "loginfo" (commit), and "notify" (watch) notifications via email, News (NNTP), and/or IRC chat (actually, "notify" is via email only). This script was written specifically for CVSNT but at least a subset of the functionality will work on any type of CVS server.

Changes

October 2 2005 version 1.9.0.21

July 5 2005 version 1.9.0.18

• Bug fix: If notify daemon was unable to send an email due to an error (e.g., smtp server down), the data to send would get corrupted; for example subject line would be blank

• "Notify" (watch) sends email immediately, unless WatchWaitSeconds in globals.xml is specified

• "Notify" (watch) now accepts %t (tag name) which will appear in the email's subject

  • ALL "dgcvsnotify" notify "%s" %t

May 22 2005 version 1.9.0.17

• The DEFAULT line in "loginfo", "notify", and "taginfo" (files that are stored in the CVSROOT folder) can optionally contain a repository name

  • e.g., loginfo;repositoryName

  • Not a new feature but was undocumented

• Added <Repository> to GlobalsDoc which has the same effect as loginfo;RepositoryName etc..

• Added <NotifySubject>, <LogInfoSubject>, and <TagInfoSubject> to GlobalsDoc

• <Repository> elements specified in CvsNotifyDoc were previously ignored

Features

• Advanced

  • Sends notifications via email (SMTP), news (NNTP), and chat (IRC)

  • Supports multiple CVS repositories on the same CVS server

• Flexible

  • Repositories and directories can have their own notification settings (e.g., send different to different email group)

  • The maximum size of messages can be specified for each type of destination. Large messages are chopped up into multiple readable messages according to these settings.

• Fast

  • Negligible impact on CVS operations

  • Similar tools require the server to wait for email messages, etc. to be sent before CVS operations can complete

• Considerate

  • Accumulates activity occurring within a given timeframe into a single message

  • For example, all commits by the user "Joe" spanning multiple modules are batched into a single email message

• Robust

  • Retries when email, etc. servers are down, so you won't lose any notifications

• Detailed

  • Nice touches like putting the branch name in the subject line

Similar Programs

• See here

• DevGuy's older CVS notification scripts

Platforms

• Only platforms supported by CVSNT (CVSNT must be running on them)

• Windows 98/NT/XP/2000/2003 Workstation and Server

• Any platform that has a Perl interpreter

• The taginfo support only works with CVSNT (which runs on Windows and Linux) but "loginfo" and "notify" will work with any CVS server

License

GNU Public License. Free to use and redistribute. If you make modifications, please post them here.

Support

• Support Forum

• DevGuy is here to help

Credits

Credits

More Information

Samples, etc.

Activity Batching

ALL PROSPECTIVE USERS MUST READ THIS!

CvsNotify batches up activity for one user, more or less. Commit, tag, and notify (watch) notifications are batched separately based on the user, the branch, and (optionally) the directory in which the commit occurs. By default, watches are not batched (see WatchWaitSeconds in GlobalsDoc).

For example, if a user issues three commits, there will only be one notification for all of the commits.

CvsNotify waits until an "inactivity" period has passed before sending notifications. The inactivity period defaults to five minutes and is configured via NotifyWaitSeconds and WatchWaitSeconds in the GlobalsDoc.

Batching serves two purposes. First, recipients aren't inundated with notifications. Secondly, it removes the load of notifications from the CVS server so that CVS operations are as fast as possible without waiting, for example, for emails to be sent. Notifications are batched for sending at a later time via a daemon program. The daemon is dgcvsnotify.exe (or .pl) running in the background. The installation instructions below will provide more details.

Sample Email Message

See here

Known Issues

• Killing the dgcvsnotify daemon can result in the loss or corruption of files that the daemon maintains. Use "dgcvsnotify stop" instead.

• There is a limitation on the total length of the command-line for loginfo which can result in errors at commit time. See http://www.devguy.com/bb/viewtopic.php?p=1109

• Batching should probably not occur across repositories

• If you provide a bogus IRC server name, the program will go into an endless loop, leaking memory until there is no memory left

• The "help" message is sent to the IRC server without any concern for flooding the server. This might trigger the server's flood detection although it hasn't on the IRC networks we've tested with. If the message was longer, it likely probably would.

• IRC doesn't support registered nicks

• IRC messages are too long particularly for large checkins, causing the channel to be unusable

  • This is why you can send "/msg nick exit" to make the bot go away

• The IRC behavior is such that the robot logs on, says what it needs to, and logs off

  • This behavior is annoying

  • This might cause the IRC server to ban the nick

  • This is necessary because IRC settings can be very dynamic via the CvsNotifyDoc file, and because Perl's threading support is still too new to properly leverage it. Each thread needs to be dedicated to a separate IRC connection.

Troubleshooting

• Here is a good thread to read. Also view the forum.

• To test email settings, run the program dgtestsmtp.exe or dgtestsmtp.pl with your email address as the first argument. If the SMTP settings are set up properly, you will receive the email.

• To test IRC settings, run dgcvsnotify passing in "irc" as the first argument followed by additional arguments. See below.

• Have you set CVSNotifyPath in the GlobalsDoc? If not, you will probably not receive notifications unless every user has the same TEMP environment variable.

• If you are using Windows, please refer to "Windows installation" below particularly at the section that discusses permissions on cmd.exe, etc.

• After performing a commit, look through the folder specified by CVSNotifyPath in the GlobalsDoc. The files are readable XML. Do the various settings to the SMTP server, etc. look correct? If they aren't, CvsNotify will continue trying to send notifications for eternity REGARDLESS OF THE CONFIGURATION SETTINGS. The configuration settings only apply to new activity. To fix the settings in the XML files in the Temp directories, modify the XML documents yourself or delete them.

• If your SMTP server's name, IRC server name, etc. changes whilst commits are occurring, or if the settings were incorrect to begin with, rest assured the notifications aren't lost. Perform the following actions:

  • Stop the dgcvsnotify daemon

  • Go to the "email" subdirectory of your CVSNotifyPath

    • Modify every err*.xml file

    • For example, for email files, replace the old server name with the new server name in the <Server> element

  • Modify the err*.xml files in the "irc", "news", etc., directories

  • Start the dgcvsnotify daemon

• If your CVS server is running on Windows and you get the following errors when you commit:

Unknown escape character '\p' ignored. Unknown escape character '\d' ignored. Unknown escape character '\c' ignored. Unknown escape character '\d' ignored. Script execution failed

Check the files in the CVSROOT folder (e.g., loginfo) and make sure you are using forward slashes instead of back slashes when specifying the path to dgcvsnotify.

Installation

CvsNotify was not meant to be used with repositories that use the :local: protocol. These scripts are meant for client-server usage. The :local: protocol should only be used when performing CVS actions from the CVS server locally.

Which Version is Installed?

Run dgcvsnotifyversion to find out. It also displays the location of the GlobalsDoc and CVSNotifyDoc files.

Installing on non-Windows Platforms

• Download and extract cvs_notify_source_*.tar.gz

• Consult UnixInstallation for more instructions

• Install Perl modules as described in UnixInstallation:

  • POE::Component::IRC

  • newslib

  • XML::Parser

    • This is included in recent versions of Perl. Run "perl -e 'use XML::Parser;'" to see if you have it. If there are no errors, you have it.

Windows Installation

• The program should be installed on a CVSNT server

• Download Windows Installer

• Add c:\program files\devguy\cvsnotify to your PATH (or where ever you decided to install the software)

• If the CVSNT server is running Windows 2003, XP, or later...

  • Make sure all of your CVS users have execute permissions on cmd.exe (e.g., c:\windows\system32\cmd.exe -- the exact path will vary if Windows isn't installed on c:)

  • Make sure all CVS users have write access to the temp folder in your windows directory (e.g., c:\winnt\temp)

  • Make sure all CVS users have "read" and "read&execute" permissions on either perl.exe or dgcvsnotify.exe (e.g., c:\program files\devguy\cvsnotify\dgcvsnotify.exe)

Installation Part 1: Customization

After modifying the XML files, you must restart the dgcvsnotify daemon

Modify the GlobalsDoc

• Optionally set Repository to give your CVS repository a name. This can be overridden in the CvsNotifyDoc. The repository name is added to email and post subjects.

• Optionally set LogInfoSubject and TagInfoSubject to specify the starting subject line for email and news posts

• Set CVSNotifyPath to c:\temp or another temporary directory - make sure all CVS users have "full control"

• Notifications are sent after an inactivity period (per user). Set NotifyWaitSeconds to alter the timeout period. Defaults to 5 minutes (300 seconds).

• IRC-related settings start with IRC

• Newsgroup-related ettings start with NNTP or News

• Set NotifyWaitSeconds and WatchWaitSeconds

If you use email, set the following elements in GlobalsDoc:

• Domain, to the default domain for "from" and "to" email addresses

• CVSEmailGroup, to a comma-delimited list of email addresses to notify upon checkin (version 1.9.0.12 and prior require all addresses on a single line in the XML file). If you omit the @ sign and the domain in the email addresses, the Domain element text is used appropriately.

• SMTPServer

• Optional: SMTPServerPort, SMTPUser, SMTPPassword

More advanced customization is available. See Installation Part 4 below.

Testing Email Settings

• Run dgtestsmtp to test your email settings. Provide your email address as the first argument. If all's well, you will receive a test email message.

Testing IRC Settings

• Run dgcvsnotify (.pl or .exe) with the first argument of irc followed by additional settings, e.g.,

  • dgcvsnotify irc Nick joe Server irc.fef.net Channel "#devguy" Message "Hello world" Debug 1

Installation Part 2: Running the dgcvsnotify daemon

A "daemon" is a program that runs in the background. The daemon's job is to send CVS notifications to users.

• Set up a daemon on the CVS server that runs run dgcvsnotify.exe / .pl when the server boots up

• On Windows, this can be done via Control Panel -> Scheduled Tasks

• On UNIX, run dgcvsnotify.pl as a UnixDaemon

If the daemon isn't running when CVS activity occurs, that activity is still captured. Nothing is lost. Once you start the daemon again, dgcvsnotify will send the notifications. In fact, if your SMTP, IRC, News, etc. server goes down, the daemon will attempt to send the message later. This feature is unique to CvsNotify within the realm of CVS scripts. CvsNotify is robust!

Installation Part 3: Configuring the CVS Server

• Within each file, you may specify a complete path to the scripts, e.g., dgloginfo, but you must use forward, not backward slashes, and if the path contains a space, enclose the entire script path in double quotes

• If you are using the Perl scripts, append .pl to the script name e.g., dgloginfo.pl

• You may optionally append ;RepositoryName to the parameter after dgcvsnotify, e.g., loginfo;Dev

• Check out the CVSROOT folder

• Modify the file "loginfo" for commit and "add new folder" notification (this is optional)

  • DEFAULT "c:\\program files\\devguy\\cvsnotify\\dgcvsnotify" loginfo ""%{sVv}"" "$USER"

  • See also: Loginfo Explanation

• Modify the file "taginfo" for tag notifications (this is optional)

  • DEFAULT "c:\\program files\\devguy\\cvsnotify\\dgcvsnotify" taginfo "$USER"

  • taginfo uses different settings than loginfo. For example, if you wish to send email when tagging, set TagInfoEmailGroup in GlobalsDoc.

  • See also: Taginfo Explanation

• Modify the file "notify" for "edit", "commit", and "unedit" notification on specific files (this is optional)

  • ALL "c:\\program files\\devguy\\cvsnotify\\dgcvsnotify" notify "%s" %t

  • If you configure notify, also modify the file "users" to specify users' email addresses (see next section)

  • See also: Notify Explanation

CVS Users File

The users file in the CVSROOT module contains lines that look like:

joeuser:jshmo@yahoo.com

CVS uses this file to map CVS user names to email addresses. CVS uses a case-sensitive lookup when searching this file. This may cause issues. Please see http://devguy.com/bb/viewtopic.php?p=1365.

CvsNotify uses this file to send emails to the correct addresses when an event occurs to a watched file. If you don't have a users file in the CVSROOT module, or if the user isn't listed in this file, the notify script appends the default email domain to the CVS user name which as specified in the GlobalsDoc file.

CvsNotify also uses this file to properly populate the "From" field when sending emails or newsgroup posts.

Installation Part 4: Advanced Customization

• This configuration allows different email addresses based on the module that is committed into, etc..

• Create a CVSNotifyDoc file

• Point GlobalsDoc to it via the CVSNotifyXML element

Stopping IRC Output

Sometimes IRC output is lengthy and uninteresting. In these cases you may send "!nick stop" to stop the IRC output. "nick" is the case-insensitive name of the IRC bot. The next CVS operation will still be output to IRC (if the configuration still applies).

Modifying Source Code on Windows Platforms

• Install ActivePerl with the Perl Package Manager option

• Install Perl modules

  • ppm install POE-Component-IRC newslib

• The source code is installed via the Windows installer. Copy c:\program files\devguy\cvsnotify\perl_lib\cfgmgmt\*.* to c:\perl\lib\cfgmgmt (c:\perl is only an example -- use the directory where Perl was installed)

PerlApp Support

PerlApp doesn't support POE programs. Here is a work-around. Run the following commands from the command line.

You only need to do this once. It's a good idea to back up your c:\perl\site\lib\poe\*.* before you do this.

• set POE_PREPROC_DUMP=c:\poe

• dgcvsnotify.pl

• terminate the dgcvsnotify program

• attrib /s -r c:\perl\site\lib\poe\*.*

• xcopy /e c:\poe\perl\site\lib\*.* c:\perl\site\lib

Ignore the following errors:

Encoding.pm:

• error: Case mismatch between module and file name refby: C:\Perl\lib\cfgmgmt\CVSNotify.pm file: C:\Perl\lib\encoding.pm

POE\.pm:

• error: Can't locate POE\.pm refby: C:\Perl\site\lib\POE.pm