From af8c598679f14b1f001b6d670b8a8e15a115e274 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= <joerg@thalheim.io>
Date: Wed, 30 Mar 2022 22:41:57 +0200
Subject: [PATCH 1/2] CONTRIBUTING: rebase master to staging without pinging
 people
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Martin Weinelt <hexa@darmstadt.ccc.de>
Co-Authored-By: Janne Heß <janne@hess.ooo>
---
 CONTRIBUTING.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f0d1ecf5aa32..183db3dac01d 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).

From 0f4a2f12afb14a429485751a394fb566a60c3b33 Mon Sep 17 00:00:00 2001
From: Martin Weinelt <hexa@darmstadt.ccc.de>
Date: Sun, 3 Apr 2022 21:07:41 +0200
Subject: [PATCH 2/2] fixup! CONTRIBUTING: rebase master to staging without
 pinging people

---
 CONTRIBUTING.md | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 183db3dac01d..0f8b5faef12d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -78,8 +78,19 @@ git rebase --onto=$common $commits
 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`.
+Then change the base branch in the GitHub PR using the *Edit* button in the upper
+right corner, and switch from `master` to `staging`. After the PR has been
+retargeted it might be necessary to do a final rebase onto the target branch, to
+resolve any outstanding merge conflicts.
+
+```console
+# Rebase onto target branch
+git rebase upstream/staging
+# Review and fixup possible conflicts
+git status
+# Force push your changes
+git push origin $(git branch --show-current) --force-with-lease
+```
 
 ## Backporting changes