From 5064ed9fd1abc20e3d6f26dadf83780f03954953 Mon Sep 17 00:00:00 2001
From: A Thousand Ships <96648715+AThousandShips@users.noreply.github.com>
Date: Sun, 3 Dec 2023 17:37:40 +0100
Subject: [PATCH] Add instructions for rebasing onto a branch

Useful if someone has created a PR from the wrong branch
---
 contributing/workflow/pr_workflow.rst | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/contributing/workflow/pr_workflow.rst b/contributing/workflow/pr_workflow.rst
index db43fb363..e722526cb 100644
--- a/contributing/workflow/pr_workflow.rst
+++ b/contributing/workflow/pr_workflow.rst
@@ -518,7 +518,7 @@ will raise an error:
     hint: Updates were rejected because the tip of your current branch is behind
     hint: its remote counterpart.
 
-This is a sane behavior, Git will not let you push changes that would
+This is reasonable behavior, Git will not let you push changes that would
 override remote content. But that's actually what we want to do here, so we
 will have to *force* it:
 
@@ -530,6 +530,31 @@ And tadaa! Git will happily *replace* your remote branch with what you had
 locally (so make sure that's what you wanted, using ``git log``). This will
 also update the PR accordingly.
 
+Rebasing onto another branch
+----------------------------
+
+If you have accidentally opened your PR on the wrong branch, or need to target another branch
+for some reason, you might need to filter out a lot of commits that differ between the old branch
+(for example ``4.2``) and the new branch (for example ``master``). This can make rebasing difficult
+and tedious. Fortunately ``git`` has a command just for this situation, ``git rebase --onto``.
+
+If your PR was created from the ``4.2`` branch and you want to update it to instead start at ``master``
+the following steps *should* fix this in one step:
+
+.. code-block:: text
+
+    $ git rebase -i --onto master 4.2
+
+This will take all the commits on your branch *after* the ``4.2`` branch, and then splice them on top of ``master``,
+ignoring any commits from the ``4.2`` branch not on the ``master`` branch. You may still need to do some fixing, but
+this command should save you a lot of tedious work removing commits.
+
+Just like above for the interactive rebase you need to force push your branch to handle the different changes:
+
+::
+
+    $ git push --force origin better-project-manager
+
 Deleting a Git branch
 ---------------------