[MERGE] Add documentation for hooks

[James Westby]

On (29/08/07 16:07), Aaron Bentley wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> Hi all,
> 
> This patch adds some documentation on hooks.  I needed to find out more
> about hooks, and I couldn't find any documentation, so I wrote some.

Hi Aaron,

This looks good and is well needed, however there is something that I
didn't quite understand.

> +post_pull
> +---------
> +Run after ``pull`` has completed.
> +
> +The hook signature is (push_result) containing the members
> +(source, local, master, old_revno, old_revid, new_revno, new_revid)
> +where local is the local target branch or None, master is the target 
> +master branch, and the rest should be self explanatory. The source
> +is read-locked and the target branches are write-locked. Source will
> +be the local low-latency branch.

The 'source', 'local' and 'master' confuse me here. I think that 'local'
is the branch that is receiving the revisions, but under what conditions
would it be None? Is the 'master' in the sense of 'master' for
checkouts? Isn't it also possible that this could be None? I would have
guessed that 'source' would be the branch that the revisions are coming
from, but this would conflict with the 'local low-latency' comment. I
realise that the local branch will now have the revisions, but what if
you want some information from the real source branch (its configuration
or similar), there doesn't seem to be any way to get it here.

Also couldn't the use of 'local' in the last sentence could be
incorrect, as 'pull -d' will allow you to pull to a remote location will
it not?

Finally I assume that the hook will not be run if there was nothing to
do, or the operation failed. It would be good to make this explicit.

Some of these comments would seem to apply elsewhere as well (especially
post_push).

I realise some of this may touch on the actual workings of the hooks,
which I realise are not the intentions of this patch.

Thanks,

James

-- 
  James Westby   --    GPG Key ID: B577FE13    --     http://jameswestby.net/
  seccure key - (3+)k7|M*edCX/.A:n*N!>|&7U.L#9E)Tu)T0>AM - secp256r1/nistp256