| ||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Chapter 11 Change Review & Other Daemons | ||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Perforce's change review functionality allows users to be notified via email whenever files that they're interested in have been updated in the depot. Since change review is provided via a background Perl script, or daemon, this functionality can be modified. Other daemons can be created to perform entirely different functions.
The primary focus of this chapter is on using the change review daemon; a secondary thread discusses how to create your own daemons. This "daemon creation" topic discusses how a daemon might be created that integrates the Perforce job tracking facilities to an external defect tracking system.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||
Providing Change Review Parameters | ||||||||||||||||||||||||||||||||||||||||||||||||||||
| Any user wishing to receive email notification of changed files must provide two pieces of information to the Perforce server: her email address, and a list of the files and directories that she wants to track (or subscribe to). This information is provided via the p4 user form. | ||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Sarah wants to be notified whenever any of the Elm README or document files are
changed. She types p4 user and fills in the resulting form with her email address and file
review list:
Once the review daemon is running, she'll be notified by email whenever any of the files in her Review: list are changed. This includes all README files, and all files in the doc subdirectory. Notification is sent whenever a changelist is submitted by any user that edits, deletes, or adds files that match the p4 user form Reviews: specification.
| Running the Daemon
Change review is implemented via a Perl script, perfreview.perl, which can be downloaded from
|
This review daemon must be run under Perl 4 or higher; Sendmail is also required. It's usually run from the p4d server account, in the same directory as the p4d server, although it can be installed anywhere. Once it's been installed, do the following:
|
|
As this manual is being finalized, additional daemons are being posted at the Perforce Web site. They are not specifically discussed here, but the techniques discussed here are used in these daemons.
| How the Review Daemon Works
The review daemon is quite simple. Every time a changelist is submitted to the Perforce depot, email is sent to every user who has subscribed to review any files that are contained in that changelist. (Unlike other job review systems that you may be familiar with, the Perforce system doesn't require the email recipient to respond; the email message is sent for notification purposes only).
| The daemon is implemented as follows:
| Tracking Reviewed Changelists with Review Counters
The review daemon needs to keep track of which changelists have already had their descriptions emailed to reviewers; in general, most Perforce daemons will need to keep track of which changelists have already been processed. The p4 review command exists to facilitate this process; it was written solely to support daemon creation and is not likely to be run by an end user.
| Every line of output produced by p4 review has the following form: Change changenum user <email_addr> (Full_Name) Change 6 edk <[email protected]> (Ed Kuepper) When used with no parameters, p4 review will output one line for every changelist that has ever been submitted. With the addition of review counter arguments, p4 review can limit its output to only those changelists not already reported. A review counter is simply a named counter; each review counter can separately track which changelists have and haven't yet been reviewed. Review counters are used in two variants of p4 review:
Review counters work by storing one counter per review counter in the Perforce database. The first variant of p4 review above sets a counter value for a particular review counter; the second variant gets the change information for all changelists numbered above that counter. The review daemon's review counter is called review; the daemon uses p4 review -t review to get a list of all unreviewed changelists, and uses p4 review -t review -c lastchangenum to store the highest numbered reviewed change number in the database under the name review.
| Perforce can store any number of review counters; each counter is identified by a unique name, which can be up to ten characters long and cannot contain whitespace. The perfreview.perl daemon's review counter is named review; if you're using perfreview.perl and are writing your own daemon, don't name the review counter review.
| Change Review and ProtectionsThe change review daemon runs at the access level of the user who invokes it (typically root), not at the access level of the user receiving email. Thus, if the daemon is edited to perform additional functionality, it should not mail out the contents of files unless it is safe for all users to see those files, since a user needs only list access in order to invoke the p4 user command to subscribe to particular files.
| Creating Other Daemons
To create another daemon, use perfreview.perl as a starting point and change it as needed. One such daemon might upload Perforce job information into an external bug tracking system after changelist submission. It would use the p4 review command with a new review counter to list new changelists, and use p4 fixes to get the list of jobs fixed by the newly submitted changelists. This information might then be fed to the external system, notifying it that certain jobs have been completed.
| If you do write a daemon of your own, and would like to share it with other users, please let us know about it at [email protected]. New daemons will be made available at
| Change Review Reporting
The change review daemon uses two reporting commands that have not yet been discussed; an additional reporting command describes the counters tracked by the p4d server: |
|
Please send comments and questions about this manual to
[email protected]. |
Copyright 1997, 1998 Perforce Software. All rights reserved. Last updated: 08/15/98 | |||||||||||||||||||||||||||||||||||