[Workflow] Best practices for stacking / chaining multiple dependent changes for review

Ideally, the solution would have the following properties:

1. The workflow for stacked PRs would be as close as possible to the normal PR workflow.
2. The same workflow would work for both maintainers and contributors.
3. It would allow any branch names to be used (i.e., no error-prone manual branch naming conventions).
4. It would prevent merging out of order and/or automatically merge in the right of order.
5. It would allow diffs to be done directly against dependent PR (i.e.,show diffs incrementally across PRs).
6. It would be easy to merge changes made in earlier dependent PRs in the chain with later ones.
7. It wouldn’t require any special shell scripts or browser extensions to work.

There are several solutions posted on various blogs, but none I’ve found so far address all of the above. Recently, we’ve been experimenting with using a custom branch naming convention (issue-##/master and issue-##/username/pr-##) + GitHub’s PR “base” feature to do this. This has several drawbacks:

• The solution requires chained PRs to be in the main repository so that maintainers can be assigned to review them. This obvious doesn’t work for contributors, who can’t add branches to the main repo. Assuming they could grant reviewers permission to review directly in their fork (extra manual step), keeping PRs in contributor forks would make them hard to find (or at worse, ephemeral, since users can delete their forks).
• It litters the main repo with many working branches that need to be cleaned up.
• It requires manual merging up the stack during review.
• It requires the reviewer to know the shouldn’t merge the PRs themselves.
• It requires the contributor to merge in a specific order, starting with the last PR down to the first to collapse and merge the stack.

Several alternatives considered that don’t meet all of the above criteria:

1. Use commits as a proxy for units of work; create one big PR and review each commit individually. https://jg.gg/2018/09/29/stacked-diffs-versus-pull-requests/
2. Do running PRs, where contributors request feedback for a small unit of work, and merge in changes only after each round of feedback.
3. Using a Chrome extension (requires full read/write access to all browser data!), and not clear if this works across forks.
4. https://graysonkoonce.com/stacked-pull-requests-keeping-github-diffs-small/: Doesn’t work across forks either, manual process.

See also:

• https://github.com/isaacs/github/issues/867
• https://github.com/isaacs/github/issues/959
• https://github.com/isaacs/github/issues/210
• https://github.com/dear-github/dear-github/issues/112

There are more but I can’t remember now. @navinsivakumar @scolsen @gyarill any thoughts?

[gino-m]

@scolsen, you pretty much nailed why I was thinking of commits as a unit of review; ideally we’d like as little manual intervention and special knowledge on the part of the contributor, both to make it easier to contribute, and to minimize work for maintainers.

@navinsivakumar I’m curious to see what you had in mind. Does it still involve creating multiple PRs? I think rebasing is scary because when done improperly it becomes a big headache to fix, but please cmiiw.

While Navin explores rebase, perhaps we can try a PR or two using commits as a proxy for reviews? I have some changes to submit that I can do that way.

[gino-m]

Iirc the consensus here was that it’s very difficult to stack PRs across forks, and that working on the main repo quickly tends to descend into chaos, so we should avoid stacking PRs. Instead, for complex PRs, we should aim to separate work into small, meaningful commits so that reviewers can view them separately if they wish. Closing this issue for now!