Could we use the new Stacked PR workflow?

GitHub recently introduced stacked pull requests, a new workflow that allows a large change to be split into several smaller, dependent pull requests.

Before discussing whether this would be useful for CPython, I would suggest reading GitHub’s announcement:

Stacked pull requests are now in public preview - GitHub Changelog

A big change used to mean one giant PR nobody wanted to review. Now it’s a stack of small ones reviewers can actually follow, and the whole stack merges in one shot

At the moment, we generally discourage using a single PR to address a large number of small issues, or to contain one very large change. Both cases tend to make review more difficult

Our usual approach is to create a parent issue, split the work into several sub-issues, and then open a separate pr for each one. This keeps individual changes focused, but it can also result in a large number of pull requests. The process becomes even more cumbersome when the changes need to be backported

Some previous groups of changes might have been suitable for a stacked pull request workflow. Examples include the series of UBSan fixes, or work such as: Speed up the parser · Issue #153568 · python/cpython · GitHub

Fix all Sphinx reference warnings in the documentation (meta issue) · Issue #151940 · python/cpython · GitHub

Would these kinds of changes be a good fit for stacked pull requests?

The most obvious use case I can think of is a set of changes that are individually simple but numerous, such as a large batch of Sphinx formatting fixes. Each layer could remain small and reviewable, while still being presented as part of one larger piece of work.

If we decide to use this feature, I think the devguide should clearly explain when stacked PR are appropriate, as well as any additional rules or expectations around their use

Something worth noting:

Stacked pull requests require all branches to be in the same repository. Cross-fork stacks are not supported.

Which I believe (but have not confirmed) means these would only work on upstream repo, if the branches of the PRs are also made on upstream repo.

2 Likes

We have turned the feature on, so if you don’t have access to it then Jakub is right and it only works in the upstream repo.

1 Like

And the core team can’t use it either because we’ve disabled creating branches in the upstream repo, so PRs must be created from personal forks.

Hopefully GitHub will allow stacked PRs from forks in the future, it currently cannot be used in many open-source projects.

2 Likes