docs: document Notifications to user

This commit is contained in:
Paul Campbell 2024-07-23 20:00:39 +01:00
parent 8f95ae0058
commit 1690e1bff6

View file

@ -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`.