Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions changelog.d/1120-publisher-fast-forward-docs.md
Original file line number Diff line number Diff line change
@@ -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).
20 changes: 13 additions & 7 deletions docs/github.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand Down
26 changes: 26 additions & 0 deletions tests/test_github_publisher.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

import json
import urllib.parse
from pathlib import Path

import pytest

Expand Down Expand Up @@ -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
Loading