Stacked Diffs

[radiradev]

What maintenance does this project need?

PRs have been becoming very long which makes reviewing collaboration and merging increasingly more difficult. One approach that has become quite prevalent in open-source project to deal with complex PRs is the concept of stacked diffs.

Stacked diffs allow to split the PR into multiple PRs where PRs are dependent on each other and are more easily digestible. This allows developers to work on features without having to wait for those to be merged into main and without increasing the complexity of the original PR.

GitHub does not natively support this feature but it supported through 3rd party extensions such as ghstack. ghstack is used for instance by the torch team - example.

Here is a diagram comparing the original workflow to that of stacked diffs from this blog.

cc: @anaprietonem @mchantry @frazane

Organisation

No response

[anaprietonem]

Hey @radiradev! looks interesting, few of questions:

• How does one control the granularity of the PRs generated? - is this controlled by the reviewer or the contributor?
• How does the CI works for unit-tests if the feature is broken down in PRs?
• How easy is then for a reviewer to checkout the branch and test the changes themselves?

[radiradev]

Hi @anaprietonem,

How does one control the granularity of the PRs generated? - is this controlled by the reviewer or the contributor?

This is up to the contributor, but reviewers can encourage it in case a PR is becoming hard to review

How does the CI works for unit-tests if the feature is broken down in PRs?

CI would treat PR in the stack independently, but considering the PRs its branched off from. As an example:
If PR#2 is branched off PR#1, PR#2 includes all the code from PR#1. When CI runs on PR#2, it’s testing the code of both PR#1 and PR#2.

How easy is then for a reviewer to checkout the branch and test the changes themselves?

With ghstack installed it is quite easy:
ghstack checkout <pull_request_url>

There are also some developer docs from torch, that you might find interesting.

[anaprietonem]

Thanks Radi this clarifies it, what I still find confusing is this sentence from the Readme: How do I merge my changes? Warning: You will NOT be able to merge these commits using the normal GitHub UI, as their branch bases won't be master.
I would assume that's not the case looking at the torch examples - do you have more context?
And if this something to be used by contributors - were you thinking about suggesting this on the README or the docs? We already try to push for breaking PRs into small sets, still we find there are times this is not easy to enforce or followed. So how do you see this being more helpful ?

[radiradev]

How do I merge my changes? Warning: You will NOT be able to merge these commits using the normal GitHub UI, as their branch bases won't be master.

I think this refers to the fact that the PRs would be structured like this:
main
└─ PR#1
----- └─ PR#2
---------- └─ PR#3

So instead one should use `ghstack land <PR_URL> so that they are merged automatically the correct order. I guess it is possible to merge them by hand but one would have to merge them in the correct order.

We already try to push for breaking PRs into small sets

I think that's exactly why that could be a good approach - without stacking one either ends up with:

• A big PR that's hard to review
• or multiple PRs that target different branches and can be confusing for developers and reviewers, in a way stacking streamlines and automates the process of splitting up a big PR into multiple ones. Encouraging the use of a certain tool would also have the stacked PRs look in the same way and create the "tree" visualization as in

I guess adding this to the docs-with a short example and perhaps update the PR template with a reminder to use a tool like ghstack (I'm not stuck on using this particular one seems like there is a plethora of tools for stacked diffs).