livery.workshop._submit¶
livery.workshop._submit ¶
fm submit: get the branch onto the remote, verified, and landed.
Local gate first (the gate the CI legs run, so a red gate costs zero network calls), then the closes-link resolution with existence probes, disarm-before-push, push, find-or-open with the title rules, arm per the arming ladder, and follow until it lands or says what stopped it. Exits 10 and 17 self-heal by integrating the base and re-submitting; every other code surfaces unchanged, because skills, hooks, and humans branch on them.
fm abandon is the exit: disarm, close the pull request, delete
both branches, return to the base. fm submit.merge merges a
green pull request that was deliberately left unarmed, and refuses
anything less than green. fm submit.arm and fm submit.disarm
set and take off a pull request's auto-merge and leave it open. The
three act on this branch's pull request, or on the one a number
names, from any checkout.
The arming ladder, highest wins: --armed/--no-armed for one
invocation; WORKSHOP_AUTOMERGE as the per-user standing preference;
the workspace contract's [ci] automerge as committed repo policy;
off. The ladder is footman's option ladder; only the printed reason
is derived here.
Classes:
| Name | Description |
|---|---|
Plan |
Everything a push and pull request need, validated, no network. |
Functions:
| Name | Description |
|---|---|
ci_automerge |
The committed repo policy: the workspace contract's |
arming_reason |
One sentence naming the ladder level that decided armed. |
branch_issue |
The issue number a |
parse_number |
Read the issue or pull request number token spells; None when it spells none. |
with_closes |
body with its |
resolve_closes |
The issue submit will link, per the three guards. |
prepare |
Validate the branch and assemble the pull request shape. |
resolve_base |
The branch the pull request targets. |
abort_if_merged |
Stop before pushing into a pull request that already merged. |
disarm_before_push |
Disarm an armed pull request before pushing to it. |
label_every_runner |
Put livery.workshop.EVERY_RUNNER_LABEL on pull request number. |
push_and_pr |
Disarm, push, find-or-open the pull request, label and arm as asked. |
refuse_ambiguous_title |
Refuse a defaulted title on a branch more than one commit ahead. |
submit_flow |
The whole submitting act; returns the pull request number. |
submit_default |
Gate, push, open-or-reuse the PR, arm, and watch it land. |
forge_failures_named |
Fail with the forge's own words when it refuses or does not answer. |
worktree_for |
The linked worktree holding branch; "" when none does or root does. |
only_local_work |
Why branch holds work that exists nowhere else; "" when safe. |
merged_pull_request |
The merged pull request branch was the head of, or None. |
teardown_branch |
The one branch teardown every stop verb wears; idempotent. |
abandon_flow |
Give the feature up: close the PR, delete both branches; idempotent. |
abandon |
Give up a feature: close the PR, delete the branches, return to base. |
pull_request_named |
Find the pull request ref numbers; this branch's when ref is empty. |
arm_flow |
Arm pr to merge when green, as |
disarm_flow |
Take auto-merge off pr and leave it open; idempotent. |
merge_flow |
Merge the pull request pr as soon as possible; a merged one is done. |
submit_merge |
Merge a PR as soon as possible: this branch's, or the one numbered. |
submit_arm |
Arm a PR to merge when green: this branch's, or the one numbered. |
submit_disarm |
Take auto-merge off a PR and leave it open: this branch's, or the one numbered. |
Attributes:
| Name | Type | Description |
|---|---|---|
submit |
|
submit
module-attribute
¶
submit = group('submit', help='Gate, push, open-or-reuse the PR, arm, and watch it land')
Plan
dataclass
¶
Plan(branch: str, base: str, title: str, body: str, title_given: bool, body_given: bool = False, subjects: tuple[str, ...] = ())
Everything a push and pull request need, validated, no network.
Attributes:
| Name | Type | Description |
|---|---|---|
branch |
str
|
The feature branch being submitted. |
base |
str
|
The branch the pull request targets. |
title |
str
|
The pull request title, validated. |
body |
str
|
The pull request body. |
title_given |
bool
|
Whether the title came from the caller. A defaulted title tracks HEAD, so only a given title may overwrite an existing pull request's. |
body_given |
bool
|
Whether the body came from the caller; the same rule for an existing pull request's body. |
subjects |
tuple[str, ...]
|
The subjects of the commits the branch carries beyond
|
ci_automerge ¶
ci_automerge() -> bool
The committed repo policy: the workspace contract's [ci] automerge.
Source code in packages/workshop/src/livery/workshop/_submit.py
arming_reason ¶
One sentence naming the ladder level that decided armed.
Source code in packages/workshop/src/livery/workshop/_submit.py
branch_issue ¶
The issue number a <type>/<number>-slug branch carries, or None.
parse_number ¶
Read the issue or pull request number token spells; None when it spells none.
The one rule every verb that takes a number from a person reads it
by. A leading # is accepted, as the forges print a number, so
#123 and 123 are the same number. Anything else that is
not all decimal digits spells no number.
Source code in packages/workshop/src/livery/workshop/_submit.py
with_closes ¶
body with its Closes #number trailer, present exactly once.
Source code in packages/workshop/src/livery/workshop/_submit.py
resolve_closes ¶
resolve_closes(repo: Repository, branch: str, closes_flag: int) -> int | None
The issue submit will link, per the three guards.
The flag beats the branch-name parse; a disagreement is printed,
never silently resolved; and the issue must exist before
Closes #N is written. A branch-parsed number that does not
exist drops the link with a note (plain branches always work); an
explicit --closes that does not exist refuses.
Source code in packages/workshop/src/livery/workshop/_submit.py
prepare ¶
prepare(root: Path, *, title: str = '', body: str = '', base: str = 'main', branch: str = '') -> Plan
Validate the branch and assemble the pull request shape.
branch is the checked-out branch when the caller read it already; read here otherwise.
Source code in packages/workshop/src/livery/workshop/_submit.py
resolve_base ¶
The branch the pull request targets.
A --base flag wins. Otherwise the parent fm start --from
recorded for the branch is the target while origin still has it,
and base once it is gone: a merged parent's branch is deleted,
and the forge retargets the child's pull request to the parent's
own base at that moment.
Origin is asked for the branch, never the remote-tracking ref: a plain fetch does not prune, so the tracking ref of a branch the forge deleted at the merge survives, and a pull request against a branch that is gone is refused with a validation error rather than a sentence.
Source code in packages/workshop/src/livery/workshop/_submit.py
abort_if_merged ¶
abort_if_merged(repo: Repository, root: Path, branch: str) -> int | None
Stop before pushing into a pull request that already merged.
The merge took the pre-push head, so pushing on would open a second pull request carrying the follow-up. That is only true when the local branch still carries the merged head: a branch with the same name cut fresh off the merged base is a new cycle (the release train reuses its reserved branch name every release), and it proceeds. Detection is best-effort: a merged pull request whose head branch is already deleted is found by head sha instead, and one invisible both ways surfaces later as the stray-PR symptom the message names.
Returns the merged pull request's number when HEAD is the head it merged: there is nothing to push, and the re-run's job is to report the merge. None when no merged pull request claims the branch or the branch is a fresh cycle.
Source code in packages/workshop/src/livery/workshop/_submit.py
disarm_before_push ¶
disarm_before_push(repo: Repository, root: Path, branch: str) -> int | None
Disarm an armed pull request before pushing to it.
A push to an armed pull request races auto-merge: the merge can take the pre-push head. The disarm narrows that window; it cannot close it, so the merged check runs after it on every path. An unreadable arming state must not block the submit; the push itself surfaces a real transport problem. Returns what livery.workshop._submit.abort_if_merged returns: the number of a pull request that already merged this very head, else None.
Source code in packages/workshop/src/livery/workshop/_submit.py
label_every_runner ¶
label_every_runner(repo: Repository, number: int) -> None
Put livery.workshop.EVERY_RUNNER_LABEL on pull request number.
The gate then runs every runner for it, where its check legs run on fewer. Idempotent: a label the pull request already carries stays. A forge that refuses, one whose repository does not carry the label among them, fails with the forge's words; the pull request exists by then, so a re-run labels the same one.
Source code in packages/workshop/src/livery/workshop/_submit.py
push_and_pr ¶
push_and_pr(repo: Repository, root: Path, plan: Plan, *, closes: int | None, armed: bool, force: bool = False, every_runner: bool = False) -> int
Disarm, push, find-or-open the pull request, label and arm as asked.
Source code in packages/workshop/src/livery/workshop/_submit.py
refuse_ambiguous_title ¶
Refuse a defaulted title on a branch more than one commit ahead.
A defaulted title is trustworthy only when it is unambiguous: one commit ahead, its subject is the intent. More, and whichever commit is HEAD would name the pull request, a guess dressed as a default, so it refuses instead, listing the subjects. A given title never refuses, and a pull request that already exists keeps its title, so the caller asks only on a first open.
Source code in packages/workshop/src/livery/workshop/_submit.py
submit_flow ¶
submit_flow(repo: Repository, root: Path, *, title: str = '', body: str = '', base: str = 'main', closes: int = 0, close: bool = True, armed: bool = False, armed_reason: str = '', gate: bool = True, fix: bool = False, force: bool = False, every_runner: bool = False, follow_to_verdict: bool = True, interval: float = 15, timeout: float = 1800) -> int
The whole submitting act; returns the pull request number.
The task shell resolves the repository, the git seam, and the arming ladder; everything after that lives here so tests drive the same flow against livery.forge.testing.FakeForge and a temporary repository.
Source code in packages/workshop/src/livery/workshop/_submit.py
940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 | |
submit_default ¶
submit_default(title: Annotated[str, doc("PR title; defaults to HEAD's subject")] = '', body: Annotated[str, doc("PR body; defaults to HEAD's body")] = '', base: Annotated[str, doc('target branch')] = 'main', closes: Annotated[int, doc('issue to close on merge; 0 = from branch name')] = 0, close: Annotated[bool, doc("close the branch's issue on merge")] = True, armed: Annotated[bool, env('WORKSHOP_AUTOMERGE'), default(ci_automerge), doc('arm auto-merge (ladder: flag, WORKSHOP_AUTOMERGE, [ci] automerge)')] = False, gate: Annotated[bool, doc(f'run `{prog()} check` first')] = True, fix: Annotated[bool, doc('heal mechanical gate findings, fold into HEAD')] = False, force: Annotated[bool, doc('force-push with a lease after a deliberate history rewrite')] = False, every_runner: Annotated[bool, doc(f"label the PR {EVERY_RUNNER_LABEL} so the gate runs every runner: for a change only another platform reaches while the pull request's legs run on fewer")] = False, follow: Annotated[bool, doc('watch until it lands or says what stopped it')] = True, interval: Annotated[int, doc('watch poll seconds')] = 15, timeout: Annotated[int, doc('watch deadline seconds')] = 1800) -> None
Gate, push, open-or-reuse the PR, arm, and watch it land.
Idempotent: re-running it is the recovery procedure. Exits 10 and
17 self-heal by integrating the base and re-submitting; the other
verdict codes surface unchanged (see livery.workshop._verdict).
--fix runs the gate's format and lint in their fix modes and
folds any rewrites into the branch before pushing: amended into
HEAD while unpushed, a follow-up commit otherwise. --no-close
submits without the close footer, for a branch that carries
preparatory work on an issue the merge must leave open.
--every-runner labels the pull request ci:every-runner, so
the gate runs every runner for it where its check legs run on
fewer: for a change to a line only another platform reaches, which
a narrowed run judges red by name.
Source code in packages/workshop/src/livery/workshop/_submit.py
1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 | |
forge_failures_named ¶
forge_failures_named() -> Generator[None]
Fail with the forge's own words when it refuses or does not answer.
A submit is safe to run again, so a read that timed out or a write the forge refused ends the run with the forge's message and that advice, not a traceback.
Source code in packages/workshop/src/livery/workshop/_submit.py
worktree_for ¶
The linked worktree holding branch; "" when none does or root does.
Source code in packages/workshop/src/livery/workshop/_submit.py
only_local_work ¶
Why branch holds work that exists nowhere else; "" when safe.
The one keep-or-drop rule: fm issue.close, fm issue.stop,
the submit's own teardown after a merge, the sweep, and fm sync
all ask it, so what they destroy is decided in one place. Dirt is
looked for where the branch actually lives: this checkout when it
stands on the branch, the branch's linked worktree otherwise.
merged_head is the head a merged pull request took. A tip equal to it holds nothing only here: the merge took every commit, and the squash rewrote them, so the remote's ancestry says nothing (after a squash the branch's commits are never ancestors of the base, and the forge deletes the remote branch). A tip past it holds the commits made after the merge. A tip the merged head does not reach was rewritten after the merge, and the ancestry rule below judges it. Without a merged head, ahead is measured against the remote branch when one exists, and against the base when none does.
Source code in packages/workshop/src/livery/workshop/_submit.py
merged_pull_request ¶
merged_pull_request(repo: Repository, root: Path, branch: str) -> PullRequest | None
The merged pull request branch was the head of, or None.
livery.workshop._forge_lane.pull_request_for finds it, by head branch and then by the branch's head commit; a forge that cannot be asked raises.
Source code in packages/workshop/src/livery/workshop/_submit.py
teardown_branch ¶
teardown_branch(repo: Repository, root: Path, branch: str, base: str) -> None
The one branch teardown every stop verb wears; idempotent.
Disarm, close the PR (a merged one is left alone), delete the
remote and local branch, and step back onto an up-to-date base
when standing on branch. Mechanism only: state gates, forces,
and refusals are the calling policy's job
(livery.workshop._submit.abandon_flow for a feature,
workflow.abort for a reserved workflow), so the policies can
never drift apart. Removing a
linked worktree moves the process into the main checkout first:
Windows refuses to remove a directory a process stands in, and
the shell that ran the verb is told where to go. A real move of
the process directory is a serial task's to make (footman refuses
it in a parallel one), so every verb that reaches this from
inside a worktree is declared serial.
Source code in packages/workshop/src/livery/workshop/_submit.py
1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 | |
abandon_flow ¶
abandon_flow(repo: Repository, root: Path, branch: str, base: str) -> None
Give the feature up: close the PR, delete both branches; idempotent.
A dirty tree refuses before anything else moves: abandoning deletes the branch, and uncommitted work must be a person's explicit loss, not a side effect.
Source code in packages/workshop/src/livery/workshop/_submit.py
abandon ¶
Give up a feature: close the PR, delete the branches, return to base.
This branch when none is named, or the named one from anywhere: its linked worktree goes with it. Disarms and closes the pull request, deletes the remote and the local branch, and leaves this checkout on an up-to-date base when it stood on the branch. A dirty tree, here or in the branch's worktree, refuses first. Idempotent: a second run finds nothing left to undo.
Source code in packages/workshop/src/livery/workshop/_submit.py
pull_request_named ¶
pull_request_named(repo: Repository, root: Path, ref: str) -> PullRequest
Find the pull request ref numbers; this branch's when ref is empty.
ref is read by livery.workshop._submit.parse_number, the
rule the issue verbs read an issue number by, so #123 and
123 name the same pull request. On the current branch the open
pull request is looked up by the branch's name, and when there is
none, a merged one by the branch's head commit, which outlives a
head branch the merge deleted: after a merge, the answer is that
it merged. Every other answer fails and names the next action: a
ref that is no number, a number no pull request has, a branch
without an open or merged pull request, and a pull request closed
without merging.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
repo
|
Repository
|
The workspace's repository on its forge. |
required |
root
|
Path
|
The checkout whose current branch an empty ref means. |
required |
ref
|
str
|
A pull request number, with or without |
required |
Returns:
| Type | Description |
|---|---|
PullRequest
|
The pull request, open or merged. What a merged one means is |
PullRequest
|
the verb's to decide. |
Source code in packages/workshop/src/livery/workshop/_submit.py
arm_flow ¶
arm_flow(repo: Repository, root: Path, pr: PullRequest) -> None
Arm pr to merge when green, as fm submit --armed arms; idempotent.
The squash takes the pull request's own title and body. An armed pull request is left as it is, and a merged one is the end the arm aims at: each line says so, and neither is an error.
Source code in packages/workshop/src/livery/workshop/_submit.py
disarm_flow ¶
disarm_flow(repo: Repository, pr: PullRequest) -> None
Take auto-merge off pr and leave it open; idempotent.
An unarmed pull request is left as it is, and the line says so. A merged one refuses: the merge the disarm was to prevent has happened.
Source code in packages/workshop/src/livery/workshop/_submit.py
merge_flow ¶
merge_flow(repo: Repository, root: Path, pr: PullRequest, *, title: str = '') -> None
Merge the pull request pr as soon as possible; a merged one is done.
Merge means merge asap, never merge-if-instant-else-fail: checks still running are followed to their verdict, the forge's own holds (the mergeability recompute, the settling beat) are followed to completion, and the task's timeout is the only backstop. Red refuses at once naming the state, behind base teaches integrate, and merging red stays a person's act in the forge's own interface.
Whether pr is behind its base is judged at HEAD when pr is this branch's pull request, since HEAD is what the next submit pushes, and at the head the forge holds for any other, which the fetch brings here. A head this clone cannot see is left to the forge's own refusal.
Source code in packages/workshop/src/livery/workshop/_submit.py
submit_merge ¶
submit_merge(pr: _PullRef = '', title: Annotated[str, doc('squash subject; defaults to the PR title')] = '') -> None
Merge a PR as soon as possible: this branch's, or the one numbered.
Waits for a running CI's verdict and follows the forge's own holds to completion; refuses red or behind-base at once, saying why, and refuses a pull request closed without merging. A pull request that has merged already is done: the verb says so and succeeds, so a re-run is the recovery. A merge that lands while it runs is success too, as livery.forge.PullRequests.merge_now reads one.
Source code in packages/workshop/src/livery/workshop/_submit.py
submit_arm ¶
Arm a PR to merge when green: this branch's, or the one numbered.
Arms as fm submit --armed arms, with the pull request's own
title as the squash subject, and reads the schedule back. A pull
request already green is merged at once, since a forge that arms
only a blocked pull request refuses. An armed one is left as it
is, and a merged one is done: the verb says so and succeeds, also
on the branch once its head branch is gone. One closed without
merging refuses.
Source code in packages/workshop/src/livery/workshop/_submit.py
submit_disarm ¶
Take auto-merge off a PR and leave it open: this branch's, or the one numbered.
The pull request and its branch stay as they are, so it waits
unmerged until fm submit.arm arms it again. An unarmed one is
left as it is. A merged one refuses, since the merge the disarm
was to prevent has happened, and so does one closed without
merging.