From 1690e1bff6a3b54ff59b0763ecc2e50c25f9b896 Mon Sep 17 00:00:00 2001
From: Paul Campbell <pcampbell@kemitix.net>
Date: Tue, 23 Jul 2024 20:00:39 +0100
Subject: [PATCH] docs: document Notifications to user

---
 crates/cli/README.md | 106 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 105 insertions(+), 1 deletion(-)

diff --git a/crates/cli/README.md b/crates/cli/README.md
index 598d75fa..714ffb1a 100644
--- a/crates/cli/README.md
+++ b/crates/cli/README.md
@@ -63,7 +63,7 @@ cargo install --path crates/cli
 
 - [x] cli
 - [x] server
-- [ ] notifications - notify user when intervention required (e.g. to rebase)
+- [x] notifications - notify user when intervention required (e.g. to rebase)
 - [ ] tui overview
 - [ ] webui overview
 
@@ -204,6 +204,110 @@ Currently `git-next` can only use a `gitdir` if the forge and repo is the
 same one specified as the `origin` remote. Otherwise the behaviour is
 untested and undefined.
 
+## Notifications
+
+`git-next` can send a number of notification to the user when intervention is required.
+Currently, only WebHooks are supported.
+
+Webhooks are sent using the Standard Webhooks format. That means all POST messages have
+the following headers:
+
+- `Webhook-Id`
+- `Webhook-Signature`
+- `Webhook-Timestamp`
+
+### Events
+
+#### Dev Not Based on Main
+
+This message `type` indicates that the `dev` branch is not based on `main`.
+
+**Action Required**: Rebase the `dev` branch onto the `main` branch.
+
+Sample payload:
+
+```json
+{
+  "data": {
+    "branches": {
+      "dev": "dev",
+      "main": "main"
+    },
+    "forge_alias": "jo",
+    "repo_alias": "kxio"
+  },
+  "timestamp": "1721760933",
+  "type": "branch.dev.not-on-main"
+}
+```
+
+#### CI Check Failed
+
+This message `type` indicates that the commit on the tip of the `next` branch has failed the
+configured CI checks.
+
+**Action Required**: Either update the commit to correct the issue CI raised, or, if the issue
+is transient (e.g. a network issue), re-run/re-start the job in your CI.
+
+Sample payload:
+
+```json
+{
+  "data": {
+    "commit": {
+      "sha": "98abef1af6825f9770d725a681e5cfc09d7fd4f2",
+      "message": "feat: add foo to bar template"
+    },
+    "forge_alias": "jo",
+    "repo_alias": "kxio"
+  },
+  "timestamp": "1721760933",
+  "type": "cicheck.failed"
+}
+```
+
+#### Repo Config Load Failed
+
+This message `type` indicates that `git-next` wasn't able to load the configuration for the
+repo from the `git-next.toml` file in the repository.
+
+**Action Required**: Review the `reason` provided.
+
+Sample payload:
+
+```json
+{
+  "data": {
+    "reason": "File not found: .git-next.toml",
+    "forge_alias": "jo",
+    "repo_alias": "kxio"
+  },
+  "timestamp": "1721760933",
+  "type": "config.load.failed"
+}
+```
+
+#### Webhook Registration Failed
+
+This message `type` indicates that `git-next` wasn't able to register it's webhook with the
+forge repository, so will not receive updates when the branches in the repo are updated.
+
+**Action Required**: Review the `reason` provided.
+
+Sample payload:
+
+```json
+{
+  "data": {
+    "reason": "repo config not loaded",
+    "forge_alias": "jo",
+    "repo_alias": "kxio"
+  },
+  "timestamp": "1721760933",
+  "type": "webhook.registration.failed"
+}
+```
+
 ## Behaviour
 
 The branch names are configurable, but we will talk about `main`, `next` and `dev`.