Development patterns¶
How to drive several changes at once with the workflow verbs, and what each pattern costs. Every verb below is described on its own task page; this page is the order to use them in.
Submit and move on¶
An armed submit needs nobody after the push. The forge merges the
pull request on its own green, closes the issue, deletes the branch,
and the next fm verb anywhere sweeps the worktree. Waiting for that
is time the next change could use.
The verb gates, pushes, opens or reuses the pull request, arms it, and
returns. Start the next change at once. Later, from any worktree,
fm ci.status says where that head's runs stand, and fm ci.logs
prints the failed jobs' logs when one is red. Only a red needs a
hand: fm ci.rerun for a runner that failed on its own, a fix
commit and fm submit --armed again for a real failure.
fm submit --armed without --no-follow watches until the merge or
the first blocker, and self-heals the two that need no decision
(behind the base, or conflicting with it) by integrating the base and
re-submitting. The re-submit is a fresh fm submit on the merged
code, so the gate judges the merged tree with the code it carries.
Use it when the merge is the next thing you need.
Several changes at once¶
Each change lives in its own worktree, started from a fetched
origin/main, with its own environment:
Worktrees are independent: a gate in one does not see another's
edits, and each submit is judged alone. fm start 123 --agent=claude
hands a worktree to a coding agent with the issue as its briefing.
Re-running fm start on started work re-enters it.
Stacking dependent changes¶
A change that needs another one's code starts on that branch instead of main, while the parent is still in review:
The worktree is added at the parent's pushed tip, and the parent is
recorded against the child's branch together with that tip, so the
commits after it are the child's own. fm submit from the child
targets the parent, so the child's pull request shows only its own
diff and gets its own CI while the parent's is still running. A
--base flag on fm submit always wins over the record.
While the parent is open, fm submit --armed from the child opens or
updates its pull request and leaves it unarmed: arming it would merge
it into the parent's branch, which has no required checks. After the
parent merges, fm sync and then fm submit --armed arm it against
main.
The child's own commits then follow the parent:
- The parent moves. When the parent gains commits or is rebased
and pushed again,
fm syncin the child moves the child's own commits onto the parent's new tip. - The parent merges. When the parent merges and origin deletes
its branch, the forge retargets the child's pull request to main.
fm sync, or the nextfm submit, then moves the child's own commits onto main, where the parent's squash already is, whatever number of commits it was made from. The push goes with a lease, and the resubmit pays one more CI run for the new head. - Only main moves. While the parent is open, main reaches the
child through it, so
fm syncleaves the child on its parent.
A conflict in the child's own commits leaves the branch as it was and
names fm sync, which offers the rebase to a person at a terminal.
fm integrate merges main in instead, which conflicts wherever the
child edited lines next to the parent's.
The parent must be pushed before the child starts on it: an unpushed parent is refused by name.
What the forge does with several green pull requests¶
Each armed pull request merges on its own green, onto whatever main is at that moment. Main moving under a pull request does not cancel its arm or its green: the branch protection does not require a branch to be up to date, so the landing order is the order in which the runs finish, and a landed pull request re-runs nothing.
Two pull requests that touch different lines both land without a
second run. The combination was proved by neither run; the next push
of anything proves it. Two that touch the same lines cannot both
apply: the forge stops the second, the watch reports it as
conflicting, and fm integrate followed by fm submit --armed
resolves it at the cost of one local gate on the changed paths and
one CI run.
Where the clock goes¶
The local gate runs what the working tree changed since the nearest
tree its record proves, so a test-only edit gates in well under a
minute and a prose-only edit in seconds. CI runs the whole gate on
every host; fm ci.timings prints each host's medians per task from
the recorded runs, and the slowest host sets the pull request's time.
A flaky test costs a whole re-run of its host every time it trips. Fixing the flake pays more than retrying it: file the issue the same day, with the log line, and fix it on its own branch while the re-run proves the change at hand.