CONTRIBUTING: rebase master to staging without pinging people

Co-Authored-By: Martin Weinelt <hexa@darmstadt.ccc.de>
Co-Authored-By: Janne Heß <janne@hess.ooo>

1 files changed, 29 insertions, 0 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f0d1ecf5aa328..183db3dac01da 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -52,6 +52,35 @@ In addition to writing properly formatted commit messages, it's important to inc
 
 For package version upgrades and such a one-line commit message is usually sufficient.
 
+## Rebasing between branches (i.e. from master to staging)
+
+From time to time, changes between branches must be rebased, for example, if the
+number of new rebuilds they would cause is too large for the target branch. When
+rebasing, care must be taken to include only the intended changes, otherwise
+many CODEOWNERS will be inadvertently requested for review.  To achieve this,
+rebasing should not be performed directly on the target branch, but on the merge
+base between the current and target branch.
+
+In the following example, we see a rebase from `master` onto the merge base
+between `master` and `staging`, so that a change can eventually be retargeted to
+`staging`. The example uses `upstream` as the remote for `NixOS/nixpkgs.git`
+while the `origin` remote is used for the remote you are pushing to.
+
+
+```console
+# Find the common base between two branches
+common=$(git merge-base upstream/master upstream/staging)
+# Find the common base between your feature branch and master
+commits=$(git merge-base $(git branch --show-current) upstream/master)
+# Rebase all commits onto the common base
+git rebase --onto=$common $commits
+# Force push your changes
+git push origin $(git branch --show-current) --force-with-lease
+```
+
+Then change the base branch in the GitHub PR with the "Edit" button in the top
+right corner, i.e. `master` → `staging`.
+
 ## Backporting changes
 
 Follow 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).