#!/usr/bin/python
# $Id:  $
#
# Perforce review daemon
#
# This script emails descriptions of new changelists and/or new or modified
# jobs to users who have expressed an interest in them.  Users express
# interest in reviewing changes and/or jobs by setting the "Reviews:" field
# on their user form (see "p4 help user").  Users are notified of changes
# if they review any file involved in that change. Users are notified of
# job updates if they review "//depot/jobs". (This value is configurable
# - see the <jobpath> configuration variable, below).
#
# If run directly with the <repeat> configuration variable = 1, the script
# will sleep for "sleeptime" seconds and then run again.  On UNIX you can
# run the script from cron by setting <repeat> = 0 and adding the following
# line to the cron table with "crontab -e:"
#
#        * * * * * /path/to/p4review.py
#
# This will run the script every minute.  Note that if you use cron you
# should be sure that the script will complete within the time allotted.
#
# The CONFIGURATION VARIABLES below should be examined and in some
# cases changed.
#
#
# Common errors and debugging tips:
#
# -> Error: "command not found" (Windows) or "name: not found" (UNIX) errors.
#
#     - On Windows, check that "p4" is on your PATH or set:
#       p4='"c:/program files/perforce/p4"' (or to the appropriate path).
#       (NOTE the use of " inside the string to prevent interpretation of
#       the command as "run c:/program with arguments files/perforce/p4...")
#
#     - On UNIX, set p4='/usr/local/bin/p4' (or to the appropriate path)
#
# -> Error: "You don't have permission for this operation"
#
#     - Check that the user you set os.environ['P4USER'] to (see below)
#       has "review" or "super" permission via "p4 protect".
#       This user should be able to run "p4 -u username counter test 42"
#       (this sets the value of a counter named "test" to 42)
#
# -> Error: "Unable to connect to SMTP host"
#
#     - check that the mailhost is set correctly - try "telnet mailhost 25"
#       and see if you connect to an SMTP server.  Type "quit" to exit
#
# -> Problem: The review daemon seems to run but you don't get email
#
#     - check the output of "p4 counters" - you should see a counter named
#       "review"
#     - check the output of "p4 reviews -c changenum" for a recent change;
#       if no one is reviewing the change then no email will be sent.
#       Check the setting of "Reviews:" on the user form with "p4 user"
#     - check that your email address is set correctly on the user form
#       (run "p4 reviews" to see email addresses for all reviewers,
#       run "p4 user" to set email address)
#
# -> Problem: Multiple job notifications are sent
#
#     - the script should be run on the same machine as the Perforce
#       server; otherwise time differences between the two machines can
#       cause problems. This is because the job review mechanism uses a
#       timestamp. The change review mechanism uses change numbers, so
#       it's not affected by this problem.


import sys, os, string, re, time, smtplib, traceback

##########################################################################
#############                                                    #########
#############      CONFIGURATION VARIABLES: CHANGE AS NEEDED     #########
#############                                                    #########
#
# In particular, be sure to set/check the first seven variables:
# <debug>, <administrator>, <mailhost>, <P4PORT>, <P4USER>, <p4>,
# and <repeat>. The script is set to run initially in "debug" mode -
# once it is configured and seems to be doing the right thing, set
# <debug> to 0.
debug = 1
    # If <debug> is true then messages go to stdout
    # and email is not actually sent to users. Instead,
    # all messages go to <administrator>, or no email
    # is sent at all if <administrator> = None. Setting
    # <debug> to larger values creates more output.

administrator = None
    # Set this to the Perforce system administrator's
    # email address. The <administrator> will be notified
    # of problems with the script (e.g. invalid
    # email addresses for users). If <bcc_admin> is set
    # <administrator> will get a copy of all email the
    # script generates.

mailhost = 'localhost'
    # The hostname of the machine running your local SMTP server.

os.environ['P4PORT'] = 'perforce:1999'
os.environ['P4USER'] = 'review_daemon'
    # This user must have Perforce review privileges (via "p4 protect")

p4 = 'p4'
    # The path of your p4 executable. You can use
    # just 'p4' if the executable is in your path.
    # NOTE: Use forward slashes EVEN ON WINDOWS,
    # since backslashes have a special meaning in Python)

repeat  = 0
    # Set to 1 to repeat every <sleeptime> seconds.
    # Set to 0 to run just once - do this if running from cron.

sleeptime = 60
    # Number of seconds to sleep between invocations
    # Irrelevant if <repeat>, above, is 0.

limit_emails = 10
    # Don't send more than this many emails of
    # each type (job and change) at a time. This is
    # a safety feature that prevents runaway email.

limit_description = 5000
    # Threshold for the number of characters permitted in a changelist
    # and job descriptions. Changelist or Job descriptions greater than
    # this value will be trunctated with a message.

notify_changes = 1
notify_jobs    = 1
    # Set <notify_changes> to 0 to disable change notification completely.
    # Set <notify_jobs>  to 0 to disable job notification completely.
    # (Note that at least ONE of these should be set to true: otherwise
    # there's no reason to ever run this program!)

bcc_admin      = 0
    # Set to 1 to Bcc: ALL email to the administrator

send_to_author = 0
    # Set to 1 to CC: email to the original author of the changelist or job

reply_to_admin = 0
    # Set to 1 to set the emails Reply-To: field to the administrator

maildomain = None
    # If value is None, the script will look up the email
    # address for each Perforce user in the "p4 user"
    # data via "p4 user -o <username>". If, instead,
    # you set this variable <maildomain> to any domain
    # (like "yourcompany.com") then the review daemon
    # will assume that Perforce user <username> has
    # the email address <username>@<maildomain>.

complain_from  = 'PerforceReviewDaemon@localhost'
    # The email address FROM which to send complaints to
    # the adminstrator from the "complain" function.

jobpath = '//depot/jobs'
    # Send job review mail to users reviewing <jobpath>.
    # See "p4 help user" for more information.

datefield = 'ModifiedDate'
    # A job field used to determine which jobs users are notified
    # of changes to. When the review daemon runs, subscribing users are
    # notified of any jobs with a higher value in this field then the
    # value in the "jobreview" counter -- and when job notification is
    # completed, the "jobreview' counter is updated accordingly.
    #
    # This field needs to appear in your jobspec as a "date" field
    # with persistence "always". See "p4 help jobspec" for more
    # information.

#############                                                    ##########
#############           END OF CONFIGURATION VARIABLES           ##########
#############                                                    ##########
###########################################################################