From 7baa194c52f9c587d5434a98f5e70270f5eb8683 Mon Sep 17 00:00:00 2001 From: unkin-agent Date: Sat, 26 Sep 2026 20:48:31 +1000 Subject: [PATCH] docs: mergeable is a plain bool, not a tri-state on the wire --- AGENTS.md | 18 ++++++++++++++---- README.md | 8 +++++++- 2 files changed, 21 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 68433d2..ff6b99d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -222,10 +222,20 @@ wrapped per stage (login / read denied / write denied) via `ErrVaultDenied`. worktree root. - `watchpr` alerts on changes, not on conditions: the baseline snapshot is a real read, so a PR that is already conflicted or already CI-failing when watching - starts is polled on rather than reported. Mergeability is the one rule needing - a run of observations (`prWatch`), because a conflict must both persist for two - polls and follow a mergeable one; Gitea's `mergeable` is tri-state (absent/null - = not yet computed) and unknown counts as neither answer. + starts is polled on rather than reported. That suppression is printed with the + baseline, since a silent watcher and a watcher with nothing to say look alike. +- Mergeability is the one `watchpr` rule needing a run of observations + (`prWatch`). Gitea 1.26 sends `mergeable` as a plain bool — always present, + never null — and sends `false` both for a real conflict and while it recomputes + the merge base after a push, which is exactly when an agent starts a watch. So + `false` counts only once this watch has seen a merge computation start (the PR + was mergeable, or `head.sha`/`base.sha` moved), and then only across two + consecutive polls of an unchanged head and base; a mergeable poll, an unknown + one or a failed poll all break the run. `base.sha` is the base branch tip as of + the response, not the merge base at PR creation, so it moves when main does. + `Mergeability` stays tri-state for what the bool cannot carry: an absent/null + flag from some other Gitea, and a state no successful poll ever filled in. + Head and base SHAs are read only to arm this rule — a push never alerts. - CI "combined status" comes from `/commits/{sha}/status`; an empty head SHA yields an empty state without an API call. - Gitea backs every PR with an issue of the same number and serves comments from diff --git a/README.md b/README.md index e09979c..f3fef7b 100644 --- a/README.md +++ b/README.md @@ -88,7 +88,13 @@ 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. +watched, and the baseline line 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. ```bash # Watch until something meaningful happens (default interval 60s)