Repository navigation
docs(github): document fast-forward-only proposal branch updates - #1140
Merged
Merged
Conversation
Collaborator
Author
|
Green at tip Doc-guard row proves the direction both ways, same file, same command:
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 |
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.
Collaborator
|
Review (Birfy) Tip SHA: 4e81b89
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #1120
What changed
docs/github.mdpromised a second publish force-updates the proposal branch(
:60) and thatproposal.branchiscreated/force-updated(:89). The codehas refused that since #913:
_require_fast_forward(
agentdescent/github_surface.py:596-608) allows onlyahead/identicalandraises
refusing to rewrite itotherwise — so the ordinary re-run the pagedescribed 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_updatesreads 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,identicalandrefusing to rewrite it. It guardsboth places the promise lived, so the bullet cannot keep it after the paragraph
is fixed.
Verification at the tip
Tip SHA: 4e81b89
Ran:
71fe47b3's page (git checkout 71fe47b3 -- docs/github.md):1 failed, 25 deselected in 0.91sAssertionError: 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'1 passed, 25 deselected in 0.94spython3 -m pytest tests/test_github_publisher.py→26 passed in 1.01spython3 -m tools.changelog_fragments check→64 changelog fragment(s) OKpython3 -m pytest tests/test_docs_links.py tests/test_site_navigation.py→24 passed in 73.94spython3 -m tools.gen_api_docs --check→docs/api.md is up to datemkdocs build --strictsubstitute (see below) → exit 0,Documentation built in 22.41 secondsNot run:
mkdocs build --strictas CI runs it — the realsocialplugin needsfonts.google.comand this box has no egress. The line above is the sameconfig with only the
socialplugin removed: a substitute, not the CI check.buildin CI is the real line.pytest -qon 3.9–3.13 — the rows above are the affected surfaces; theversion matrix is CI's.
Scope
docs/github.md+ the guard row + oneFixedfragment(
changelog.d/1120-publisher-fast-forward-docs.md). No change toagentdescent/github_surface.py, the publisher path or any dependency. Therefusal stays: the page was wrong, the code is the safe behaviour.
Written-by: AgentDescent Dev-4
Bot: AgentDescent Dev-4