AccuRev Trigger Library (actriggerlib) - README

Overview
========

  This library exists to provide support for AccuRev triggers.  I wrote this
  library because I wanted a facility to unit test individual trigger handlers
  as triggers can change with great frequency as a corporation custom modifies
  their AccuRev SCM process.  The original perl-based triggers are single pass,
  functional-oriented scripts that, _while written elegently_ (yo Brad!), don't
  support unit testing individual handlers that are essentially mutually exclusive.
  
  Ruby to the rescue.

  I hope you find this library equally as useful as I do.


Installation
============

See INSTALL for installation instructions.

Project Layout
==============

  /INSTALL                 -- installation guide
  /COPYING                 -- this is free software; as in 'free speech', not 'free beer'
  /CHANGES                 -- release notes
  /TODO                    -- more work to do on the libraries
  /README                  -- this.file
  /server_admin_trig.rb    -- server-side admin trigger script.
  /lib                     -- where the .rb rtrigger libraries live
  /test                    -- unit tests for the trigger libraries
  /doc                     -- rdoc generated api docs


Customizing Triggers
====================

  Customizing triggers is simple, even if you are new to Ruby.  The trigger library
  (lib/actriggerlib.rb) is a collection of  modules that contains (static/non-mixin)
  methods, one for each trigger.  The name of the trigger (must) matches the command
  being executed (eg. AcTriggerLib.chuser) since the method is called dynamically
  at runtime.  All supported trigger methods have a default implementation.

  The return value of the trigger method, 0 or non-0, determines if the requested
  operation succeeds or fails, respectively.  Any valid ruby code in the trigger along
  with desired conditions is enough to customize a trigger!

  Strongly consider writing unit test(s) for changes to a trigger.  The entire reason
  this library exists in the first place is to provide a framework for testing changes
  to triggers.  Simply copy an existing unit test and add input and test conditions.
  Simple as that!

  The server_admin_trig.rb entry point (called by the AccuRev server) to the trigger
  library should not need to be customized.  Therefore, restarting the server is not
  necessary if modifications occur in the trigger library itself (lib/actriggerlib.rb).


Developer Notes
===============

  ** How The Admin Triggers Work

  In a nutshell, the AccuRev server receives a request to execute a command
  and forwards the request to the server_admin_trig trigger script.  The command
  request comes in the form of an XML message.  The server saves the XML request
  to a temporary file and gives the temporary filename to the trigger script as
  arg[0]. The XML is extracted and converted into a 'dynamic xml object' with
  getter methods that match the elements (eg. obj.stream1, obj.principal).
  This 'xml object' defines, among other things, the command being issued.
  The command is used to call a specific method on the AcAdminTrigger module
  that defines triggers for all handled methods.  The return status of the
  trigger method determines sucess or failure of the trigger.  This way,
  only code for the specific trigger is executed; no big if/else or
  switch/case block to trickle down into.

  The actriggerlib depends on, and is shipped with, a compatible version
  of an accurev xml parser that is part of the acrubylib package (separate).

  ** Debugging
 
  Look for 'DEBUG' in the code.  These are points where useful debugging options exist.
  Simply uncomment the code block.  For example, server_admin_trig.rb file has a feature
  that dumps the incoming XML to /tmp so the original input xml can be viewed.  This is
  especially useful for obtaining real XML to be used in test cases.

  ** XML Format

  The following XML format represents all fields sponsored by the <triggerInput/> root.
  Though, for any given <command/>, the actuall elements will vary.  AccuRev currently
  does not have public DTD's; this format was generated based on their published example
  PERL admin script and experience unit testing all possible commands.

    <triggerInput>                  # required
        <hook></hook>               # required
        <command></command>         # required
        <principal></principal>     # required
        <ip></ip>                   # required
        <stream1></stream1>
        <stream2></stream2>
        <stream3></stream3>
        <depot></depot>
        <objectType></objectType>
        <objectName></objectName>
        <user></user>
        <newKind></newKind>
        <newName></newName>
        <fromClientPromote></fromClientPromote>
        <changePackagePromote></changePackagePromote>
        <comment></comment>
    </triggerInput>


Feedback
========

    Questions/Comments/Suggestions?

              davidpthomas at gmail.com
              www.fepus.net


Enjoy -- dave

                                            Use ViM.  It's good for your health.