From d2990717f165acba5817d20f332159c797fad508 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Na=C3=AFm=20Favier?= Date: Sun, 29 May 2022 21:53:19 +0200 Subject: [PATCH] CONTRIBUTING.md: simplify rebasing instructions Makes the instructions easier to remember (and type) using the `git rebase --onto A...B` syntax to find the merge base between A and B (which has been in git for at least 10 years). We also assume that the merge base between staging and master is also the merge base between staging and the current branch (since it is based on master), and giving master as the branch makes git consider the commits in the current branch that are not in master, so there's no need to compute the merge base between master and the current branch. In the same spirit of discouraging copy-and-paste, use a placeholder name for the current branch instead of `$(git branch --show-current)`. --- CONTRIBUTING.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 46e3ea5b2240..0268d640a9a2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -62,25 +62,26 @@ 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. +In the following example, we assume that the current branch, called `feature`, +is based on `master`, and we rebase it onto the merge base between +`master` and `staging` so that the PR can eventually be retargeted to +`staging` without causing a mess. The example uses `upstream` as the remote for `NixOS/nixpkgs.git` +while `origin` is 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 +# Rebase your commits onto the common merge base +git rebase --onto upstream/staging... upstream/master # Force push your changes -git push origin $(git branch --show-current) --force-with-lease +git push origin feature --force-with-lease ``` +The syntax `upstream/staging...` is equivalent to `upstream/staging...HEAD` and +stands for the merge base between `upstream/staging` and `HEAD` (hence between +`upstream/staging` and `upstream/master`). + 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 +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. @@ -90,7 +91,7 @@ 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 +git push origin feature --force-with-lease ``` ## Backporting changes