docs: name the conflict watchpr will never report
ci/woodpecker/pr/pre-commit Pipeline was successful
ci/woodpecker/pr/build Pipeline was successful
ci/woodpecker/pr/test Pipeline was successful

This commit is contained in:
2026-09-26 21:14:20 +10:00
parent 15c527ee56
commit 91509cb9b2
2 changed files with 28 additions and 11 deletions
+12 -4
View File
@@ -88,13 +88,21 @@ gets a **new comment from someone other than the agent**, its **CI fails**
transitions — CI `pending`→`success`, the agent's own comments and pushes — are
ignored, and so is any condition the PR was already in at the baseline: a PR
that is already conflicted or already failing when watching starts keeps being
watched, and the baseline line says which conditions it is staying silent about.
watched, and the baseline line — written to stderr, as a JSON record under
`--json` — says which conditions it is staying silent about.
Gitea reports `mergeable: false` both for a real conflict and while it
recomputes the merge base after a push, so a conflict is only reported once the
watch has seen a merge computation start — the PR was mergeable, or its head or
base commit moved — and then only across two consecutive polls of an unchanged
head and base.
watch has seen a merge computation start (the PR was mergeable, or its head or
base commit moved) **and** the non-mergeable polls have then run unbroken for
two minutes. The debounce is a duration, not a poll count, because what it has
to outlast is Gitea's recompute and `--interval` ranges from seconds to hours.
One case is therefore never reported: a conflict introduced by the push
immediately before the watch started, on a PR whose head and base never move
again. Nothing in Gitea's payload separates that from a merge check still in
flight, so watchpr stays silent about it for as long as it runs — the baseline
line is how you see it.
```bash
# Watch until something meaningful happens (default interval 60s)