Mercurial > hgbook
comparison en/hook.tex @ 134:b727a63518d4
Minor updates to race description.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Fri, 21 Jul 2006 22:42:19 -0700 |
parents | d1a3394f8bcf |
children | 0707489b90fd |
comparison
equal
deleted
inserted
replaced
41:d1a3394f8bcf | 134:b727a63518d4 |
---|---|
146 permanent, and reject it if it fails to pass the test suite. If | 146 permanent, and reject it if it fails to pass the test suite. If |
147 people only pull changes from this filtering server, it will serve to | 147 people only pull changes from this filtering server, it will serve to |
148 ensure that all changes that people pull have been automatically | 148 ensure that all changes that people pull have been automatically |
149 vetted. | 149 vetted. |
150 | 150 |
151 \section{Using hooks with shared access to a repository} | 151 \section{Care with \texttt{pretxn} hooks in a shared-access repository} |
152 | 152 |
153 If you want to use hooks to so some automated work in a repository | 153 If you want to use hooks to so some automated work in a repository |
154 that a number of people have ahred access to, you need to be careful | 154 that a number of people have shared access to, you need to be careful |
155 in how you do this. | 155 in how you do this. |
156 | 156 |
157 Mercurial only locks a repository when it is writing to the | 157 Mercurial only locks a repository when it is writing to the |
158 repository, and only the parts of Mercurial that write to the | 158 repository, and only the parts of Mercurial that write to the |
159 repository pay attention to locks. Write locks are necessary to | 159 repository pay attention to locks. Write locks are necessary to |
188 Some controlling hooks (\hook{pretxncommit} and | 188 Some controlling hooks (\hook{pretxncommit} and |
189 \hook{pretxnchangegroup}) run when a transaction is almost complete. | 189 \hook{pretxnchangegroup}) run when a transaction is almost complete. |
190 All of the metadata has been written, but Mercurial can still roll the | 190 All of the metadata has been written, but Mercurial can still roll the |
191 transaction back and cause the newly-written data to disappear. | 191 transaction back and cause the newly-written data to disappear. |
192 | 192 |
193 If one of these hooks runs for long, it opens a window in which a | 193 If one of these hooks runs for long, it opens a window of time during |
194 reader can see the metadata for changesets that are, strictly | 194 which a reader can see the metadata for changesets that are not yet |
195 speaking, not yet permanent. The longer the hook runs, the bigger the | 195 permanent, and should not be thought of as ``really there''. The |
196 window. | 196 longer the hook runs, the longer that window is open. |
197 | 197 |
198 A good use for the \hook{pretxnchangegroup} hook would be to | 198 \subsection{The problem illustrated} |
199 automatically build and test incoming changes before they are accepted | 199 |
200 into the repository, so that you can guarantee that nobody can push | 200 In principle, a good use for the \hook{pretxnchangegroup} hook would |
201 changes to this repository that ``break the build''. But if a client | 201 be to automatically build and test incoming changes before they are |
202 can pull changes while they're being tested, the usefulness of the | 202 accepted into a central repository. This could let you guarantee that |
203 test is zero; someone can pull untested changes. | 203 nobody can push changes to this repository that ``break the build''. |
204 | 204 But if a client can pull changes while they're being tested, the |
205 The safest answer to this challenge is to set up such a ``gatekeeper'' | 205 usefulness of the test is zero; an unsuspecting someone can pull |
206 repository as \emph{unidirectional}. It can take changes pushed in | 206 untested changes, potentially breaking their build. |
207 from the outside, but nobody can pull changes from it. Use the | 207 |
208 \hook{preoutgoing} hook to lock it down. Configure a | 208 The safest technological answer to this challenge is to set up such a |
209 \hook{changegroup} hook so that if a build or test succeeds, the hook | 209 ``gatekeeper'' repository as \emph{unidirectional}. Let it take |
210 will push the new changes out to another repository that people | 210 changes pushed in from the outside, but do not allow anyone to pull |
211 \emph{can} pull from. | 211 changes from it (use the \hook{preoutgoing} hook to lock it down). |
212 Configure a \hook{changegroup} hook so that if a build or test | |
213 succeeds, the hook will push the new changes out to another repository | |
214 that people \emph{can} pull from. | |
215 | |
216 In practice, putting a centralised bottleneck like this in place is | |
217 not often a good idea, and transaction visibility has nothing to do | |
218 with the problem. As the size of a project---and the time it takes to | |
219 build and test---grows, you rapidly run into a wall with this ``try | |
220 before you buy'' approach, where you have more changesets to test than | |
221 time in which to deal with them. The inevitable result is frustration | |
222 on the part of all involved. | |
223 | |
224 An approach that scales better is to get people to build and test | |
225 before they push, then run automated builds and tests centrally | |
226 \emph{after} a push, to be sure all is well. The advantage of this | |
227 approach is that it does not impose a limit on the rate at which the | |
228 repository can accept changes. | |
212 | 229 |
213 \section{A short tutorial on using hooks} | 230 \section{A short tutorial on using hooks} |
214 \label{sec:hook:simple} | 231 \label{sec:hook:simple} |
215 | 232 |
216 It is easy to write a Mercurial hook. Let's start with a hook that | 233 It is easy to write a Mercurial hook. Let's start with a hook that |