Nixpkgs Pull Request Testing, Branch Management, and Backporting

For more details on writing and running tests, see the [section in the NixOS manual](https://nixos.org/nixos/manual/index.html#sec-nixos-tests). #### Tested compilation of all pkgs that depend on this change using `nixpkgs-review` If you are modifying a package, you can use `nixpkgs-review` to make sure all packages that depend on the updated package still build. It can work on uncommitted changes with the `wip` option or on a specific pull request. Review changes from pull request number 12345: ```ShellSession nix-shell -p nixpkgs-review --run "nixpkgs-review pr 12345" ``` Alternatively, with flakes (and analogously for the other commands below): ```ShellSession nix run nixpkgs#nixpkgs-review -- pr 12345 ``` Review uncommitted changes: ```ShellSession nix-shell -p nixpkgs-review --run "nixpkgs-review wip" ``` Review changes from the last commit: ```ShellSession nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD" ``` #### Tested execution of all binary files (usually in `./result/bin/`) It's important to test a modified package's executables. Look into `./result/bin` and run all files in there, or at a minimum, the main executable. For example, if you make a change to `texlive`, you probably would only check the binaries associated with the change you made, rather than testing all of them. #### Meets Nixpkgs contribution standards The last checkbox is about whether it fits the guidelines in this `CONTRIBUTING.md` file. This document details our standards for commit messages, reviews, licensing of contributions, etc... Everyone should read and understand these standards before submitting a pull request. ### Rebasing between branches (i.e. from `master` to `staging`) Sometimes, changes must be rebased between branches. One example is, if the number of rebuilds caused is too large for the original target branch. In the following example, the current `feature` branch is based on `master`, and we rebase it to have the PR target `staging`. We rebase on the _merge base_ between `master` and `staging` to avoid too many local rebuilds. ```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 use the *Edit* button in the upper right corner of the GitHub PR, and switch the base branch from `master` to `staging`. *After* the PR has been retargeted, a final rebase onto the target branch might be needed to resolve 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 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.

This chunk details further requirements for Nixpkgs pull requests, including using `nixpkgs-review` to test dependent packages with various commands (for PRs, uncommitted changes, or last commit), and testing the execution of binary files. It also highlights adherence to Nixpkgs contribution standards outlined in `CONTRIBUTING.md`. The document then explains how to rebase a feature branch between different base branches (e.g., from `master` to `staging`) using `git rebase --onto` and force-pushing, followed by updating the PR's base branch on GitHub. Finally, it covers the process of backporting merged pull requests, either automatically by Nixpkgs maintainers using specific GitHub labels, or manually by creating a new PR against the `release-YY.MM` branch and using `git cherry-pick -x` for each commit.