SCM Gate-side hooks TOI
-----------------------

1. General overview
The OSOL0scm package installs the SCM hooks, and needs to be installed on both
oss-nfs1 & oss-app{1,2}.  hg.os.o is a CNAME to www.os.o, and forwards to the
VIP which handles the failover between oss-app{1,2}.  So, nominally it will
go to oss-app1 until app1 fails, at which point it will go to app2.

On both the app servers, /hg/<project> is an NFS mount to oss-nfs1.  The same
path is LOFS mounted on nfs1 so you can access the repos from the same /hg/
path on either machine.  The gate hooks are loaded in via the repository's
.hgrc file, e.g. /hg/scm-migration/onnv-scm/.hg/hgrc
The oddity is that hgrc is a symlink to the gate hooks installed by the
OSOL0scm package in /usr/share/lib/scm:

[Astevel@oss-app1:.hg] 503$ ll hgrc
lrwxrwxrwx   1 root     root          26 Feb  6  2007 hgrc -> /usr/share/lib/scm/hg/hgrc*

What this means is that if you are interacting with the repo while logged into
nfs1, you are technically running different hooks than if you are logged into
app1/2.  If all the hooks are kept in sync (by installing the same package on
all machines), then that's not an issue.  One "feature" of this is that you can
install new hooks on a machine like app2 and test them out by interacting with
app2 instead of hg.os.o.

/usr/share/lib/scm/hg/hgrc is a pretty basic hgrc and sets hooks for the
pretxnchangegroup and changegroup actions.  These are loaded from the
scmhooks.hg module, which can be found in
/opt/dscm/lib/python2.4/scmhooks/hg.py

2. SFW testing of gate-side hooks
If you login to nfs1 & app1, you'll notice app1's common.py & hg.py differ from
nfs1, and that there is a hg_test.py as well.  This is due to the gate hook
testing I was doing to enable/disable gate-side checks triggered by incoming
changesets (e.g. a push).  If you look at the sfwnv/test_stevel repository,
you'll see it has its own hgrc (rather than a symlink to
/usr/share/lib/scm/hg/hgrc like all the other hg repositories) that instead
loads the scmhooks.hg_test module and enables/disables checks via the [gate]
section.  This is how we'd planned to support things like rejecting pushes
based on cstyle failure, cddlchk failure, etc.  These putback checks should
just reference the same Cddl/Comments/Copyright modules we implemented for
onnv-scm so there is no code duplication.
(This does mean that you need to have those modules installed on the gate
machine though, obviously... as you can see from our install of SUNWonbld
on oss-app1 - which, now that I think about it, should definitely be updated)

3. Code overview
common.py & hg.py is where most of the functionality you'll care about lives
Comments should probably live within the code better, but this will have to
suffice for now.

authorToEmail(author):
	takes an author string of the 3 forms specified in the comments,
	and attempts to parse a login out of it and map it to an OpenSolaris
	user and email address.

notify():
	builds/sends a notification email for the given node ID/changeset

aggregateNotify():
	builds/sends an aggregate notification email for the set of changesets
	passed in the list 'changesets'

keywords():
	unused.

pretxnchangegroup():
	the actual hook tied into the hgrc file.  Tests the locking
	restrictions (i.e. is the repository locked via the webapp?).

changegroup():
	the actual hook tied into the hgrc file.  Triggers the notification
	mechanism (i.e. notify() or aggregateNotify() depending on the # of
	changesets)

SFW hg_test.py module overview:
	The majority of this module is the same as hg.py since it clearly should
	subsume its functionality at some point.
	The key differences are the chk_* functions, which are essentially just
	wrappers around the various onbld modules found in /opt/onbld/lib.
	There is a pbchk() routine which loads the modules, and checks the
	repository's hgrc file to see if any checks are disabled.  By turning
	on 'pbchecks', all child checks default to the enabled state.  The
	pbcheck() routine then checks to turn off any individual checks which
	specify the disabled state in the hgrc.

	The pretxnchangegroup() hook includes a change to check for the
	'pbchecks' being enabled, if so, it runs the checks on the incoming
	changegroup which will return either success or failure.