Backporting and Reviewing Pull Requests in Nixpkgs

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 be retargeted to `staging`. The example uses `upstream` as the remote for `NixOS/nixpkgs.git` while `origin` is the remote you are pushing to. ```console # Rebase your commits onto the common merge base git rebase --onto upstream/staging... upstream/master # Force push your changes 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 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 feature --force-with-lease ``` ## How to backport pull requests Once a pull request has been merged into `master`, a backport pull request to the corresponding `release-YY.MM` branch can be created either automatically or manually. ### Automatically backporting changes > [!Note] > You have to be a [Nixpkgs maintainer](./maintainers) to automatically create a backport pull request. Add the [`backport release-YY.MM` label](https://github.com/NixOS/nixpkgs/labels?q=backport) to the pull request on the `master` branch. This will cause [a GitHub Action](.github/workflows/backport.yml) to open a pull request to the `release-YY.MM` branch a few minutes later. This can be done on both open or already merged pull requests. ### Manually backporting changes To manually create a backport pull request, follow [the standard pull request process][pr-create], with these notable differences: - Use `release-YY.MM` for the base branch, both for the local branch and the pull request. > [!Warning] > Do not use the `nixos-YY.MM` branch, that is a branch pointing to the tested release channel commit - Instead of manually making and committing the changes, use [`git cherry-pick -x`](https://git-scm.com/docs/git-cherry-pick) for each commit from the pull request you'd like to backport. Either `git cherry-pick -x <commit>` when the reason for the backport is obvious (such as minor versions, fixes, etc.), otherwise use `git cherry-pick -xe <commit>` to add a reason for the backport to the commit message. Here is [an example](https://github.com/nixos/nixpkgs/commit/5688c39af5a6c5f3d646343443683da880eaefb8) of this. > [!Warning] > Ensure the commits exists on the master branch. > In the case of squashed or rebased merges, the commit hash will change and the new commits can be found in the merge message at the bottom of the master pull request. - In the pull request description, link to the original pull request to `master`. The pull request title should include `[YY.MM]` matching the release you're backporting to. - When the backport pull request is merged and you have the necessary privileges you can also replace the label `9.needs: port to stable` with `8.has: port to stable` on the original pull request. This way maintainers can keep track of missing backports easier. ## How to review pull requests > [!Warning] > The following section is a draft, and the policy for reviewing is still being discussed in issues such as [#11166](https://github.com/NixOS/nixpkgs/issues/11166) and [#20836](https://github.com/NixOS/nixpkgs/issues/20836). The Nixpkgs project receives a fairly high number of contributions via GitHub pull requests. Reviewing and approving these is an important task and a way to contribute to the project. The high change rate of Nixpkgs makes any pull request that remains open for too long subject to conflicts that will require extra work from the submitter or the merger. Reviewing pull requests in a timely manner and being responsive to the comments is the key to avoid this issue. GitHub provides sort filters that can be used to see the [most recently](https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc) and the [least recently](https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-asc) updated pull requests. We highly encourage looking at [this list of ready to merge, unreviewed pull requests](https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+review%3Anone+status%3Asuccess+-label%3A%222.status%3A+work-in-progress%22+no%3Aproject+no%3Aassignee+no%3Amilestone).

This section explains how to backport pull requests from the `master` branch to stable release branches (release-YY.MM) in Nixpkgs, both automatically and manually. It details the process of using `git cherry-pick` to apply commits to the release branch and how to create a backport pull request, including linking to the original pull request and setting appropriate labels. It also covers how to review pull requests, encouraging timely responses to avoid conflicts due to the high change rate in Nixpkgs, and suggests useful GitHub filters for finding pull requests that need review.