Nixpkgs Pull Request Backporting and Review Guidelines

Once a PR has been merged, a backport to the corresponding `release-YY.MM` branch can be created. ### 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 PR on the `master` branch. This will cause [a GitHub Action](.github/workflows/backport.yml) to open a new PR 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, follow [the standard pull request process][pr-create], but: - 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. > It points to the latest _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. Use `git cherry-pick -x <commit>` when the reason is obvious, for example for minor version bumps and fixes. Otherwise, use `git cherry-pick -xe <commit>` to add a reason for the backport. Here is [an example](https://github.com/nixos/nixpkgs/commit/5688c39af5a6c5f3d646343443683da880eaefb8). > [!Warning] > Ensure the commits exist 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. ## How to review pull requests The Nixpkgs project receives a high number of pull requests. Anyone may review and approve PRs and it is an important contribution to the project. The high change rate makes any PR that remains open for too long subject to merge conflicts. To avoid extra work, reviewing PRs timely and being responsive is key. GitHub provides sort filters to see the [most recently updated](https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc) 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+no%3Aproject+no%3Aassignee+no%3Amilestone). Controversial changes can lead to controversial opinions, but it is important to respect every community member and their work. Always be nice and polite. GitHub provides reactions for quick feedback to pull requests or comments. The thumb-down reaction should be used with care and, if possible, accompanied with explanation for the submitter to improve their contribution. When doing a review: - Aim to drive the proposal to a timely conclusion. - Focus on the proposed changes and keep the scope narrow. - Help the contributor prioritise their efforts towards getting their change merged. If you find anything related that could be improved but is not immediately required for acceptance, consider: - Implementing the changes yourself in a follow-up pull request, - Tracking your idea in an issue, - Offering to review a follow-up pull request, - Making concrete [suggestions](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request) in the same pull request. For example, follow-up changes could involve refactoring code in the affected files. But please remember not to make such additional considerations a blocker, and communicate that to the contributor, for example by following the [conventional comments](https://conventionalcomments.org) pattern. If the related change is essential for the contribution at hand, make clear why you think it is important to address that first. Pull request reviews should include a list of what has been reviewed in a comment, so other reviewers and mergers can know the state of the review.

This document outlines procedures for backporting merged pull requests and guidelines for reviewing them in the Nixpkgs project. Backporting can be automatic for maintainers via a GitHub label and action, creating a PR to `release-YY.MM`. Manual backporting involves creating a new PR against `release-YY.MM` (not `nixos-YY.MM`), using `git cherry-pick -x` or `-xe` for commits (noting rebased/squashed commits), linking to the original PR, and including `[YY.MM]` in the title. PR review guidelines encourage timely, responsive reviews from anyone to prevent merge conflicts. Reviewers should be polite, focus on proposed changes to conclude them, and provide clear feedback. Non-blocking improvements should be considered for follow-up, while essential changes must be addressed, and all reviews should list what was covered.