PATTERN Cited by 1 source

First-class commit-stack workflow

Design the VCS so that working in a stack of small, individually reviewed commits is a comfortable default workflow — not a manual rebase dance layered on top of a non-stack-aware tool.

Canonical instance: Sapling. The design stance is explicit in the 2022-11-15 announcement post:

"Sapling makes this easy by providing explicit commands and workflows for making even the newest engineer able to edit, rearrange, and understand the commits in the stack."

— Sapling announcement post

Ingredients

1. A stack-tracking storage layer. The VCS must remember, for every commit, the mutation lineage that produced it — every amend, rebase, fold, split produces a new commit linked to its predecessor. Canonical wiki concept: concepts/mutation-history-commit.
2. Named commands for stack moves. Sapling's disclosed surface:
3. sl goto COMMIT — check out any commit in the stack.
4. sl amend — edit the current commit, auto-move the top of the stack onto the amended commit.
5. sl restack — algorithmically rebuild the stack after any intervening mutations (Sapling figures out the new parent relationships from mutation history).
6. sl next / sl prev / sl goto top / sl goto bottom — navigate the stack.
7. sl fold / sl split — combine or split commits in place.
8. sl absorb — automatically push uncommitted working-copy changes into the "right" commit in the stack.
9. sl amend --to COMMIT — target an arbitrary commit by name.
10. Deferred conflict resolution. "If you choose not to fix the conflicts now, you can continue working on that commit, and later run sl restack to bring your stack back together once again." I.e. the mutation history lets a stack be in a "broken" state across arbitrary unrelated work.
11. A stack-aware review tool (separate concern). Sapling points at ReviewStack as the demo of what per-commit review UX looks like — a critique of the non-stack GitHub PR review model.

Why the tooling investment is justified

The naive alternative — git rebase -i for every stack edit — creates a cognitive tax every time the engineer wants to iterate on a commit other than the tip. For teams whose unit of review is the commit (Meta, Google's Gerrit ecosystem, etc.), that tax is paid daily. Sapling folds the whole surface into named, idempotent commands and the mutation-history substrate makes them safe.

The pattern pairs with patterns/usability-first-vcs-cli (the general design stance) and patterns/vcs-undo-tooling (the recovery substrate that makes bad stack moves cheap to undo).

Seen in

• sources/2024-09-10-meta-sapling-source-control-thats-user-friendly-and-scalable — canonical-first wiki instance. Meta's internal VCS is engineered around the commit-stack workflow being the default.

Related

• systems/sapling-scm — the canonical instance.
• systems/reviewstack — the stack-aware review tool demo.
• concepts/commit-stack — the unit of work.
• concepts/mutation-history-commit — the substrate that makes stack-editing commands safe.
• patterns/usability-first-vcs-cli — the broader design stance.
• patterns/vcs-undo-tooling — the recovery pattern that pairs.