Skip to content

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.

fm submit --armed --no-follow

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:

fm start 123
fm start "the title of a new issue"
fm start docs/a-note

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:

fm start 124 --from=feat/123-the-parent

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 sync in 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 next fm 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 sync leaves 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.