diff --git a/changelog.d/1120-publisher-fast-forward-docs.md b/changelog.d/1120-publisher-fast-forward-docs.md new file mode 100644 index 00000000..827cba66 --- /dev/null +++ b/changelog.d/1120-publisher-fast-forward-docs.md @@ -0,0 +1,4 @@ +Fixed +The GitHub publisher page now documents fast-forward-only proposal branch +updates: a second publish of a `behind` or `diverged` branch is refused with +`refusing to rewrite it` instead of promising a force update (#1120). diff --git a/docs/github.md b/docs/github.md index 528bb448..63287ca3 100644 --- a/docs/github.md +++ b/docs/github.md @@ -57,11 +57,16 @@ proposal or printed. The publisher creates blobs, a tree over the base tree, a commit whose parent is the base head, the proposal branch, the PR (or updates an existing PR for the -same head/base) and the labels/check. A second publish force-updates only the -proposal branch; the base branch is never touched. An existing PR's title and -body are refreshed, but its draft state is left alone. Label and check-run -failures after the branch/PR exist are reported under `warnings` instead of -aborting a half-written publish. +same head/base) and the labels/check. A second publish updates the proposal +branch only as a fast-forward: the compare against the new base must be `ahead` +(the branch head is already contained in the base) or `identical`. Anything +else, including the ordinary case where the previous publish's commit sits on a +base that has not moved (`behind`), is refused with `refusing to rewrite it`; +the base branch is never touched. To recover from a refusal, wait until the +base contains the proposal's head and re-run, or publish under a new branch +name. An existing PR's title and body are refreshed, but its draft state is +left alone. Label and check-run failures after the branch/PR exist are reported +under `warnings` instead of aborting a half-written publish. ## Status @@ -86,8 +91,9 @@ read-only. code in the existing sandbox/runner, never on the publisher host with secrets. - **Secrets.** The token is read from the environment at request time. Do not put it in a proposal, a commit, a check summary or a log. -- **Base branch.** Only `proposal.branch` is created/force-updated; a proposal - whose branch equals the base is refused. +- **Base branch.** Only `proposal.branch` is created, and an existing one is + updated only as a fast-forward (`ahead` or `identical`); a branch that would + need a rewrite is refused, as is a proposal whose branch equals the base. ## What this is not yet diff --git a/tests/test_github_publisher.py b/tests/test_github_publisher.py index 9876a5da..abb254b4 100644 --- a/tests/test_github_publisher.py +++ b/tests/test_github_publisher.py @@ -2,6 +2,7 @@ import json import urllib.parse +from pathlib import Path import pytest @@ -552,3 +553,28 @@ def test_an_approval_with_an_action_word_does_not_block_readiness(monkeypatch): assert payload["merge_readiness"]["ready"] is True by_text = {row["text"]: row["severity"] for row in payload["constraints"]} assert by_text["Approved - no changes required."] == "suggestion" + + +DOCS_GITHUB = Path(__file__).resolve().parents[1] / "docs" / "github.md" + + +def test_publisher_page_documents_fast_forward_only_updates(): + """The page must not promise the force update `_require_fast_forward` refuses. + + Guards both places that used to promise it (#1120): the publish paragraph + and the base-branch bullet. It asserts the rule, not the wording, so a later + edit of the prose is not blocked. + """ + page = DOCS_GITHUB.read_text(encoding="utf-8") + for number, line in enumerate(page.splitlines(), start=1): + if "force-updat" in line.lower(): + condition = ("fast-forward" in line.lower() or "`ahead`" in line + or "`identical`" in line or "refus" in line.lower()) + assert condition, ( + "docs/github.md promises a force update without naming the " + f"fast-forward condition or the refusal (line {number}): " + f"{line.strip()!r}") + lowered = page.lower() + assert "fast-forward" in lowered + assert "`ahead`" in page and "`identical`" in page + assert "refusing to rewrite it" in page