@@ -52,6 +52,46 @@ In addition to writing properly formatted commit messages, it's important to inc
5252
5353For package version upgrades and such a one-line commit message is usually sufficient.
5454
55+## Rebasing between branches (i.e. from master to staging)
56+
57+From time to time, changes between branches must be rebased, for example, if the
58+number of new rebuilds they would cause is too large for the target branch. When
59+rebasing, care must be taken to include only the intended changes, otherwise
60+many CODEOWNERS will be inadvertently requested for review. To achieve this,
61+rebasing should not be performed directly on the target branch, but on the merge
62+base between the current and target branch.
63+
64+In the following example, we see a rebase from `master` onto the merge base
65+between `master` and `staging`, so that a change can eventually be retargeted to
66+`staging`. The example uses `upstream` as the remote for `NixOS/nixpkgs.git`
67+while the `origin` remote is used for the remote you are pushing to.
68+
69+
70+```console
71+# Find the common base between two branches
72+common=$(git merge-base upstream/master upstream/staging)
73+# Find the common base between your feature branch and master
74+commits=$(git merge-base $(git branch --show-current) upstream/master)
75+# Rebase all commits onto the common base
76+git rebase --onto=$common $commits
77+# Force push your changes
78+git push origin $(git branch --show-current) --force-with-lease
79+```
80+
81+Then change the base branch in the GitHub PR using the *Edit* button in the upper
82+right corner, and switch from `master` to `staging`. After the PR has been
83+retargeted it might be necessary to do a final rebase onto the target branch, to
84+resolve any outstanding merge conflicts.
85+
86+```console
87+# Rebase onto target branch
88+git rebase upstream/staging
89+# Review and fixup possible conflicts
90+git status
91+# Force push your changes
92+git push origin $(git branch --show-current) --force-with-lease
93+```
94+
5595## Backporting changes
5696
5797Follow these steps to backport a change into a release branch in compliance with the [commit policy](https://nixos.org/nixpkgs/manual/#submitting-changes-stable-release-branches).