[RFC/PATCH] Writing hooks doc

[Brian de Alwis]

This is very timely for me as I'm just writing my clear-exec-bit hook  
as suggested by Michael Hudson, and I'm just learning Python too.  I  
found it helpful, even in an incomplete state.

W.r.t. your current text:

   * Be sure to explicitly name the hooks being used.  For example,  
the "Hello world" hook is 'pre_commit'; the check_maintainers_file  
is...  I'm not sure?

   * I liked the section on "Making a hook configurable".  The other  
hook examples I've found use 'on' rather than enabled/'yes'.  Maybe an  
aside that an explicit "_enabled" allows future extensibility for  
separating configuration details.

   * the check_maintainers_file is overwhelming.  An obvious question  
is: why wouldn't you just open the MAINTAINERS file directly?


My difficulties writing a hook were:

   * Determining what the parameters actually were: I was writing a  
pre-commit hook and wasn't sure which of the 8 parameters was a branch  
from which to get a base to provide to the LocationConfig.  (The  
second argument, called "master", appears to be the right thing,  
though I'm still not certain what it represents.)

   * Finding a simple example:  None of the examples were for a  
pre_commit hook.  It would be especially nice if there was a simple  
skeleton for a pre-commit hook that executes some shell script for the  
non-python people (like me :-)

   * Determining the operating environment: It's not clear to me what  
directory the hooks are executed from.  Apparently it's the current  
directory.  How would I find the repository root?  (And perhaps  
symmetry on what a hook is expected to not do, such as changing the  
current directory?)

   * How to raise an error to abort the commit: is raising  
bzrlib.errors.TipChangedRejected the right thing for pre-commit hooks?

Brian.


On 22-Jul-2008, at 5:07 PM, Andrew Bennetts wrote:

> Hi,
>
> This patch isn't complete, but I thought I should send what I had  
> and get some
> early feedback.  It adds some text to the User Guide to explain in  
> more detail
> how to write a useful hook.
>
> I used my experience with writing the example GNOME  
> pre_change_branch_tip hooks
> as a guide.
>
> Things I'm not fully satisfied with:
>
> * all the XXXs :)
> * particularly the XXX about terminology: “hook” vs. “hook  
> function”
> * I'm not sure if the User Guide is the best place for this doc, but  
> the admin
>   guide is just a stub at the moment.
> * the “Getting the contents of a file at some revision” section  
> is pretty
>   messy.  I think ideally we'd just have a simpler API rather than a  
> doc
>   explaining how to deal with a complicated one that is easy to get  
> wrong.
>
> So this isn't really ready for merging, but I wanted to get some  
> feedback.
>
> -Andrew.
>
> <writing-hook-docs.patch>

-- 
  Brian de Alwis | Software Practices Lab | UBC | http://www.cs.ubc.ca/~bsd/
       "Amusement to an observing mind is study." - Benjamin Disraeli