docs: add a little documentation on hooks.

Updates: #1586465 Signed-off-by: Kyle Fazzari <kyle@canonical.com> 

1 files changed, 31 insertions, 0 deletions

diff --git a/docs/hooks.md b/docs/hooks.md
new file mode 100644
index 0000000000..0dae15166e
--- /dev/null
+++ b/docs/hooks.md
@@ -0,0 +1,31 @@
+# Hooks
+
+There are a number of situations where snapd needs to notify a snap that
+something has happened. For example, when a snap is upgraded, it may need to run
+some sort of migration on the previous version's data in order to make it
+consumable by the new version. Or when an interface is connected or
+disconnected, the snap might need to obtain attributes specific to that
+connection. These types of situations are handled by hooks.
+
+A hook is defined as an executable contained within the `meta/hooks/` directory
+inside the snap. The file name of the executable is the name of the hook (e.g.
+the upgrade hook executable would be `meta/hooks/upgrade`).
+
+As long as the file name of the executable corresponds to a supported hook name,
+that's all one needs to do in order to utilize a hook within their snap. Note
+that hooks, like apps, are executed within a confined environment. By default
+hooks will run with no plugs; if a hook needs more capabilities one can use the
+top-level attribute `hooks` in `snap.yaml`, like so:
+
+ hooks: # Top-level YAML attribute, parallel to `apps`
+ upgrade: # Hook name, corresponds to executable name
+ plugs: [network] # Or any other plugs required by this hook
+
+Note that hooks will be called with no parameters. If they need more information
+from snapd they can utilize the `snapctl` command.
+
+
+## Supported Hooks
+
+**Note:** The development of specific hooks is ongoing. None are currently
+supported.