1.1 --- a/en/hook.tex	Thu Jul 20 19:42:50 2006 -0700
     1.2 +++ b/en/hook.tex	Fri Jul 21 22:42:19 2006 -0700
     1.3 @@ -148,10 +148,10 @@
     1.4  ensure that all changes that people pull have been automatically
     1.5  vetted.
     1.6  
     1.7 -\section{Using hooks with shared access to a repository}
     1.8 +\section{Care with \texttt{pretxn} hooks in a shared-access repository}
     1.9  
    1.10  If you want to use hooks to so some automated work in a repository
    1.11 -that a number of people have ahred access to, you need to be careful
    1.12 +that a number of people have shared access to, you need to be careful
    1.13  in how you do this.
    1.14  
    1.15  Mercurial only locks a repository when it is writing to the
    1.16 @@ -190,25 +190,42 @@
    1.17  All of the metadata has been written, but Mercurial can still roll the
    1.18  transaction back and cause the newly-written data to disappear.
    1.19  
    1.20 -If one of these hooks runs for long, it opens a window in which a
    1.21 -reader can see the metadata for changesets that are, strictly
    1.22 -speaking, not yet permanent.  The longer the hook runs, the bigger the
    1.23 -window.
    1.24 -
    1.25 -A good use for the \hook{pretxnchangegroup} hook would be to
    1.26 -automatically build and test incoming changes before they are accepted
    1.27 -into the repository, so that you can guarantee that nobody can push
    1.28 -changes to this repository that ``break the build''.  But if a client
    1.29 -can pull changes while they're being tested, the usefulness of the
    1.30 -test is zero; someone can pull untested changes.
    1.31 -
    1.32 -The safest answer to this challenge is to set up such a ``gatekeeper''
    1.33 -repository as \emph{unidirectional}.  It can take changes pushed in
    1.34 -from the outside, but nobody can pull changes from it.  Use the
    1.35 -\hook{preoutgoing} hook to lock it down.  Configure a
    1.36 -\hook{changegroup} hook so that if a build or test succeeds, the hook
    1.37 -will push the new changes out to another repository that people
    1.38 -\emph{can} pull from.
    1.39 +If one of these hooks runs for long, it opens a window of time during
    1.40 +which a reader can see the metadata for changesets that are not yet
    1.41 +permanent, and should not be thought of as ``really there''.  The
    1.42 +longer the hook runs, the longer that window is open.
    1.43 +
    1.44 +\subsection{The problem illustrated}
    1.45 +
    1.46 +In principle, a good use for the \hook{pretxnchangegroup} hook would
    1.47 +be to automatically build and test incoming changes before they are
    1.48 +accepted into a central repository.  This could let you guarantee that
    1.49 +nobody can push changes to this repository that ``break the build''.
    1.50 +But if a client can pull changes while they're being tested, the
    1.51 +usefulness of the test is zero; an unsuspecting someone can pull
    1.52 +untested changes, potentially breaking their build.
    1.53 +
    1.54 +The safest technological answer to this challenge is to set up such a
    1.55 +``gatekeeper'' repository as \emph{unidirectional}.  Let it take
    1.56 +changes pushed in from the outside, but do not allow anyone to pull
    1.57 +changes from it (use the \hook{preoutgoing} hook to lock it down).
    1.58 +Configure a \hook{changegroup} hook so that if a build or test
    1.59 +succeeds, the hook will push the new changes out to another repository
    1.60 +that people \emph{can} pull from.
    1.61 +
    1.62 +In practice, putting a centralised bottleneck like this in place is
    1.63 +not often a good idea, and transaction visibility has nothing to do
    1.64 +with the problem.  As the size of a project---and the time it takes to
    1.65 +build and test---grows, you rapidly run into a wall with this ``try
    1.66 +before you buy'' approach, where you have more changesets to test than
    1.67 +time in which to deal with them.  The inevitable result is frustration
    1.68 +on the part of all involved.
    1.69 +
    1.70 +An approach that scales better is to get people to build and test
    1.71 +before they push, then run automated builds and tests centrally
    1.72 +\emph{after} a push, to be sure all is well.  The advantage of this
    1.73 +approach is that it does not impose a limit on the rate at which the
    1.74 +repository can accept changes.
    1.75  
    1.76  \section{A short tutorial on using hooks}
    1.77  \label{sec:hook:simple}