riff

    The app

    Stacks and dependencies

    How riff shows stacked PRs and Jira dependency links, and what merges first.

    Stacked PRs and Jira links tell you what has to land before a PR can. Riff reads both, folds a stack into one row, and warns before you merge out of order.

    Stacked PRs

    A stack is a chain of PRs where each builds on the one below it. Riff finds one two ways:

    • GitHub’s native stacks (made with the gh-stack extension), when GitHub knows the stack.
    • Base-branch chains: a PR whose base branch is another open PR’s head branch.

    In the PR list a stack is one row, listed base first. It sits in the section of its most urgent PR, with a summary such as “1 CI failing · 2 ready”. Press x to expand it to every layer. A PR waiting on the one below shows “Approved · waits on #123”.

    The stack bar

    On a PR page, a bar under the tabs shows the stack with this PR marked. Each layer has a state: Merged, Closed, Draft, Approved, Changes or Open. Click a layer to go to it. Long stacks fold merged layers, then distant layers, into one entry that opens a menu. On the Summary and Review tabs, [ and ] move to the layer below and above. The Jira card in the details column also lists the nearest layers under Same stack.

    The Summary tab adds an Order gate, “Merges after the layer below it”, with a card for that layer. It is shown while the layer below is not merged.

    When a PR names a Jira ticket in its branch or title, riff reads the ticket’s links. Set Jira up in Jira.

    Link Meaning
    Blocked by These tickets must ship before this PR
    Blocks These tickets wait on this PR
    Duplicates, Relates to Listed together under Relates to on the PR’s Jira card, never waited on

    Each linked ticket shows its PRs and a stage:

    Stage Meaning
    Open A PR is still open
    Merged PRs merged, ticket not done yet
    Released The ticket has shipped
    No PR No PR is known for it

    A ticket has shipped when its status is one of your configured released statuses, or, if you set none, when it is in Jira’s Done category.

    The Deps slot

    The status line of every row, and the PR header, has a Deps slot:

    • Waits on api #8133 (warning): a blocker has not shipped. The PR’s next step says “Waits on …” when nothing else holds it.
    • Unblocks API-12 (info): other tickets wait on this PR.

    The PR page shows the same as gates:

    • Depends: “Blocked by 2 tickets that have not shipped”, with a card per blocker and its PR. It turns green when every dependency is released.
    • Unblocks: tickets waiting on this one.

    If tickets block each other in a loop, the epic grouping flags it instead of ordering them (see below).

    Merge guard

    Merging a PR whose ticket still has unshipped blockers asks first, and Merge anyway is your call. See Pull requests.

    Group by epic or team

    The list’s Group by control has three modes:

    • Sections: the default ranking by what needs you.
    • Epic: PRs grouped under their Jira epic, each epic in merge order. “No epic” comes last.
    • Team: PRs grouped under the Jira team of their ticket, your team first. “No team” comes last.

    Merge order

    Inside an epic, PRs are listed in the order they have to merge. A PR merges after:

    • its base PR, when it is a layer of a stack, or
    • the PRs of tickets that block its ticket, which must be released first.

    Each row says which earlier steps it follows. If the epic’s PRs wait on each other in a loop, riff shows a warning and falls back to the list’s own order.

    Grouping works from tickets riff has already read. A PR with no ticket lands under “No epic” or “No team”.

    From the terminal

    Terminal window
    riff pr status owner/repo#42 # deps and stack of one PR
    riff pr inbox --all --group epic # each epic in merge order
    riff pr inbox --all --group team
    riff pr merge 42 --ignore-deps # skip the merge guard

    See riff pr for the JSON shape.