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).