Dependencies and stacked pull requests
Some changes have to land in order: a feature's second part needs code that its first part adds. A build packet can record the packets it builds on, so the order is kept in Retain instead of in someone's head, and your coding agent builds each one from the right starting point. This page covers how that works and how to set it.
What a dependency is
A packet's dependencies are other packets in the same repository that must come first. A packet can't depend on itself, two packets can't depend on each other, and a name Retain doesn't know is refused. Retain keeps each dependency by the packet itself, so renaming a packet doesn't break the packets that build on it.
When a dependency is ready
A dependency is ready when it has something to build on. That means one of:
- It has a linked pull request that is open, a draft or merged.
- It is built or archived.
It does not need to be merged, tested or archived first. A dependency with no pull request, or only a closed one, is not ready. A dropped one is not ready either, and says so.
If a pull request exists but was never linked to its packet, the dependency reads as having none. Link it from the dependency's Build tab: on the Mac, Find pull requests looks for it, and on both Mac and iPhone you can paste its address.
What the agent does with them
When you ask your agent to build a packet that has dependencies, it first reads each dependency's pull requests again from GitHub and reports which are ready. Without GitHub access on that computer, it works from what Retain last stored and says so. Then it chooses where to start:
- One dependency has an open pull request. The agent starts your branch from that dependency's branch and opens your pull request against it. This is a stacked pull request: it shows only your change, and it can be reviewed while the one beneath it is still in review. If that pull request is only a suggestion you haven't confirmed, the agent asks before stacking on it.
- Several dependencies have open pull requests. The agent lists them and asks which branch to start from.
- The dependencies merged, or are built or archived. The agent starts from the default branch, which already holds their code.
Keeping a stacked build in step after its dependency changes or merges stays with your repository's own stacking tools. Retain doesn't rebase for you.
When one is not ready
The agent stops before it claims or builds anything. It names each dependency that isn't ready with the reason in words, and asks whether to build anyway from the default branch, or to stop. Nothing starts until you answer. If you only asked it to write the requirements and tasks for review, it says so and goes on, since writing them needs no dependency.
On the Build tab
When a packet has dependencies or dependents, its Build tab shows two read-only sections:
- Depends on. Each packet this one builds on, with its state, whether it is ready, the reason, and a link to the pull request to stack onto when there is an open one. A line saying the packet is waiting on its dependencies leads the section, and the section sits above the start commands, so a blocked packet reads as blocked before you copy anything. When every dependency is ready, the section sits below the pull requests. A dependency that no longer exists reads "No longer exists".
- Needed by. The packets that build on this one, each with its state.
Select a row to open that packet. A packet with neither shows the tab without either heading.
The apps show what Retain last stored. It is refreshed whenever an agent checks or reads pull requests, so a row can lag behind GitHub until then.
The Work list doesn't mark blocked packets. The place to see the order is the Build tab.
Set or change dependencies
When you write a design with /retain:design, your agent asks whether the change builds on other packets of this repository, and lists the candidates. It adds only the ones you choose. See Explore, design, apply.
Later, tell your agent in plain words, such as "make this packet depend on build-claims" or "remove the dependency on build-claims". The apps don't edit dependencies. An archived or dropped packet is read-only and can't be changed.
Picking what's next leaves out packets whose dependencies aren't ready.
Need help?
Can't find what you're looking for? Contact our support team for a quick reply.
Contact Support