Skip to content

docs(github): document fast-forward-only proposal branch updates - #1140

Merged
Birfy merged 1 commit into
mainfrom
agent/1120-publisher-fast-forward-docs
Nov 17, 2026
Merged

Birfy merged 1 commit into
mainfrom
agent/1120-publisher-fast-forward-docs

Conversation

@HugoXK

@HugoXK HugoXK commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Fixes #1120

What changed

docs/github.md promised a second publish force-updates the proposal branch
(:60) and that proposal.branch is created/force-updated (:89). The code
has refused that since #913: _require_fast_forward
(agentdescent/github_surface.py:596-608) allows only ahead/identical and
raises refusing to rewrite it otherwise — so the ordinary re-run the page
described was the exact path that fails.

The page now states the fast-forward-only rule, names both allowed statuses,
names the refusal, and gives the operator the recovery (wait until the base
contains the proposal head, or publish under a new branch name). No code changed.

New offline guard
tests/test_github_publisher.py::test_publisher_page_documents_fast_forward_only_updates
reads the page, fails if any line claims a force update without naming the
fast-forward condition or the refusal, and asserts the page names
fast-forward, ahead, identical and refusing to rewrite it. It guards
both places the promise lived, so the bullet cannot keep it after the paragraph
is fixed.

Verification at the tip

Tip SHA: 4e81b89

Ran:

  • red — new row against 71fe47b3's page (git checkout 71fe47b3 -- docs/github.md): 1 failed, 25 deselected in 0.91s
  • red assertion, verbatim: AssertionError: docs/github.md promises a force update without naming the fast-forward condition or the refusal (line 60): 'same head/base) and the labels/check. A second publish force-updates only the'
  • green — same row, edited page: 1 passed, 25 deselected in 0.94s
  • python3 -m pytest tests/test_github_publisher.py → 26 passed in 1.01s
  • python3 -m tools.changelog_fragments check → 64 changelog fragment(s) OK
  • python3 -m pytest tests/test_docs_links.py tests/test_site_navigation.py → 24 passed in 73.94s
  • python3 -m tools.gen_api_docs --check → docs/api.md is up to date
  • mkdocs build --strict substitute (see below) → exit 0, Documentation built in 22.41 seconds

Not run:

  • mkdocs build --strict as CI runs it — the real social plugin needs
    fonts.google.com and this box has no egress. The line above is the same
    config with only the social plugin removed: a substitute, not the CI check.
    build in CI is the real line.
  • full pytest -q on 3.9–3.13 — the rows above are the affected surfaces; the
    version matrix is CI's.

Scope

docs/github.md + the guard row + one Fixed fragment
(changelog.d/1120-publisher-fast-forward-docs.md). No change to
agentdescent/github_surface.py, the publisher path or any dependency. The
refusal stays: the page was wrong, the code is the safe behaviour.

Written-by: AgentDescent Dev-4
Bot: AgentDescent Dev-4

@HugoXK HugoXK added documentation Improvements or additions to documentation area:docs Documentation site (docs/, mkdocs.yml) and README agent-pr Pull request opened by an agent labels Nov 17, 2026
@HugoXK
HugoXK requested a review from Birfy November 17, 2026 00:44
@HugoXK

HugoXK commented Nov 17, 2026

Copy link
Copy Markdown
Collaborator Author

Green at tip 4e81b89757ac213adddc8f0ff00c648b011ce976, head unchanged since this PR opened: build, otel-wire, test (3.9)–(3.13) all success, deploy skipped, both report-only rows success. Reviewing this sha.

Doc-guard row proves the direction both ways, same file, same command:

  • on 71fe47b3's page with only this test file present → 1 failed, 25 deselected, AssertionError: docs/github.md promises a force update without naming the fast-forward condition or the refusal (line 60);
  • on this tip → 1 passed, 25 deselected; whole file 26 passed.

The page now names the fast-forward rule at both places that carried the promise (the publish paragraph and the base-branch bullet), states the two allowed compare statuses ahead/identical, and gives the operator the recovery (wait for the base to contain the head, or publish under a new branch name).

The page promised that a second publish force-updates the proposal branch,
but `_require_fast_forward` allows only `ahead`/`identical` and raises
`refusing to rewrite it` otherwise, so the ordinary re-run is refused.

Say what the code does, name both allowed statuses and the refusal, and give
the operator the recovery. A doc-guard row reads the page offline so the
promise cannot drift back through either place that carried it.
@github-actions github-actions Bot added the risk:T1 Risk tier T1 (tests, examples, changelog.d), set by the controller from the diff label Nov 17, 2026
@Birfy

Birfy commented Nov 17, 2026

Copy link
Copy Markdown
Collaborator

Review (Birfy)

Tip SHA: 4e81b89
Ran:

  • .github/scripts/risk_gate.py --pr 1140 → T1 (50 lines / 3 files)
  • pytest -q tests/test_github_publisher.py → 26 passed at this tip
  • the new guard row against main's docs/github.md (fcebbdf) → 1 failed, red at line 60: "A second publish force-updates only the" without naming the fast-forward condition or the refusal
  • python -m tools.changelog_fragments check → 64 changelog fragment(s) OK
  • python -m tools.gen_api_docs --check → docs/api.md is up to date
  • CI at this tip → required checks green (build, test 3.9–3.13); otel-wire SUCCESS; deploy skipped; risk tier and reviewed tip are report-only SUCCESS
    Not run:
  • mkdocs build --strict locally — the CI build job is green at this tip
  • Full offline suite locally — the CI test matrix is the line
  • Ark real-model run — no model path changed
    Findings:
  • none
    Verdict: PASS

@Birfy
Birfy merged commit 00b46e1 into main Nov 17, 2026
10 checks passed
@Birfy
Birfy deleted the agent/1120-publisher-fast-forward-docs branch November 17, 2026 04:23
HugoXK added a commit that referenced this pull request Nov 18, 2026
Forward-merge after #1138/#1140/#1139/#1147/#1148/#1151/#1152 landed.
#1148 rewrites agentdescent/pilot.py, the file this branch patches; the
auto-merge keeps both the per-seed _next_actions branch and the
notes/strategy card addition, and the focused set is green at the
merge tree.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agent-pr Pull request opened by an agent area:docs Documentation site (docs/, mkdocs.yml) and README documentation Improvements or additions to documentation risk:T1 Risk tier T1 (tests, examples, changelog.d), set by the controller from the diff

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs(github): the publisher page promises a force update the code refuses

2 participants