Improve hooks documentation structure Split synchronous and asyncronous hooks into separate sections, and move the duplicated paragraphs about syncronous hook behavior into the top of the syncronous hooks section. Replace legacy section heading formatting (===== and ----- forms), which only supports 2 levels, with newer formatting (starting the line with one or more # marks) which supports further levels. Add a table of contents. Change-Id: Iacf7c44860ec4d77e44c9816fc04ea641a2c8b43
diff --git a/src/main/resources/Documentation/hooks.md b/src/main/resources/Documentation/hooks.md index 1fcb0c9..c4622cc 100644 --- a/src/main/resources/Documentation/hooks.md +++ b/src/main/resources/Documentation/hooks.md
@@ -1,8 +1,15 @@ -Supported Hooks -=============== +# Supported Hooks -ref-update ----------- +[TOC] + +## Synchronous Hooks + +These hooks are invoked synchronously so it is recommended that they not block. + +A default timeout on the hook is set to 30 seconds to avoid "runaway" hooks using +up server threads. The timeout can be changed by setting [`hooks.syncHookTimeout`][1]. + +### ref-update This is called when a ref update request is received by Gerrit. It allows a request to be rejected before it is committed to the Gerrit repository. If @@ -10,32 +17,26 @@ output from the script will be returned to the user, regardless of the return code. -This hook is called synchronously so it is recommended that it not block. A -default timeout on the hook is set to 30 seconds to avoid "runaway" hooks using -up server threads. See [`hooks.syncHookTimeout`][1] for configuration details. - ``` ref-update --project <project name> --refname <refname> --uploader <uploader> --oldrev <sha1> --newrev <sha1> ``` -commit-received ---------------- +### commit-received This is called when a push request is received by Gerrit. It allows a push to be rejected before it is committed to the Gerrit repository. If the script exits with non-zero return code the push will be rejected. Any output from the script will be returned to the user, regardless of the return code. -This hook is called synchronously so it is recommended that it not block. A -default timeout on the hook is set to 30 seconds to avoid "runaway" hooks using -up server threads. See [`hooks.syncHookTimeout`][1] for configuration details. - ``` commit-received --project <project name> --refname <refname> --uploader <uploader> --oldrev <sha1> --newrev <sha1> --cmdref <refname> ``` -patchset-created ----------------- +## Asynchronous Hooks + +These hooks are invoked asynchronously on a background thread. + +### patchset-created Called whenever a patchset is created (this includes new changes and drafts). @@ -46,8 +47,7 @@ The `--kind` parameter represents the kind of change uploaded. See documentation of [`patchSet`][2] for details. -draft-published ---------------- +### draft-published Called whenever a draft change is published. @@ -55,8 +55,7 @@ draft-published --change <change id> --change-url <change url> --change-owner <change owner> --project <project name> --branch <branch> --topic <topic> --uploader <uploader> --commit <sha1> --patchset <patchset id> ``` -comment-added -------------- +### comment-added Called whenever a comment is added to a change. @@ -64,8 +63,7 @@ comment-added --change <change id> --is-draft <boolean> --change-url <change url> --change-owner <change owner> --project <project name> --branch <branch> --topic <topic> --author <comment author> --commit <commit> --comment <comment> [--<approval category id> <score> --<approval category id> <score> --<approval category id>-oldValue <score> ...] ``` -change-merged -------------- +### change-merged Called whenever a change has been merged. @@ -73,8 +71,7 @@ change-merged --change <change id> --change-url <change url> --change-owner <change owner> --project <project name> --branch <branch> --topic <topic> --submitter <submitter> --commit <sha1> --newrev <sha1> ``` -change-abandoned ----------------- +### change-abandoned Called whenever a change has been abandoned. @@ -82,8 +79,7 @@ change-abandoned --change <change id> --change-url <change url> --change-owner <change owner> --project <project name> --branch <branch> --topic <topic> --abandoner <abandoner> --commit <sha1> --reason <reason> ``` -change-restored ---------------- +### change-restored Called whenever a change has been restored. @@ -91,8 +87,7 @@ change-restored --change <change id> --change-url <change url> --change-owner <change owner> --project <project name> --branch <branch> --topic <topic> --restorer <restorer> --commit <sha1> --reason <reason> ``` -ref-updated ------------ +### ref-updated Called whenever a ref has been updated. @@ -100,8 +95,7 @@ ref-updated --oldrev <old rev> --newrev <new rev> --refname <ref name> --project <project name> --submitter <submitter> ``` -project-created ---------------- +### project-created Called whenever a project has been created. @@ -109,8 +103,7 @@ project-created --project <project name> --head <head name> ``` -reviewer-added --------------- +### reviewer-added Called whenever a reviewer is added to a change. @@ -118,8 +111,7 @@ reviewer-added --change <change id> --change-url <change url> --change-owner <change owner> --project <project name> --branch <branch> --reviewer <reviewer> ``` -reviewer-deleted ----------------- +### reviewer-deleted Called whenever a reviewer (with a vote) is removed from a change. @@ -127,8 +119,7 @@ reviewer-deleted --change <change id> --change-url <change url> --change-owner <change owner> --project <project name> --branch <branch> --reviewer <reviewer> [--<approval category id> <score> --<approval category id> <score> ...] ``` -topic-changed -------------- +### topic-changed Called whenever a change's topic is changed from the Web UI or via the REST API. @@ -136,8 +127,7 @@ topic-changed --change <change id> --change-owner <change owner> --project <project name> --branch <branch> --changer <changer> --old-topic <old topic> --new-topic <new topic> ``` -hashtags-changed ----------------- +### hashtags-changed Called whenever hashtags are added to or removed from a change from the Web UI or via the REST API. @@ -156,8 +146,7 @@ hashtag remaining on the change after the add or remove operation has been performed. -cla-signed ----------- +### cla-signed Called whenever a user signs a contributor license agreement.