Nixpkgs Package Removal and Testing Guidelines

2. If a git repository is not already present, create one and stage all of the source files. ```ShellSession $ git init $ git add -A ``` 3. Edit some files to make whatever changes need to be included in the patch. 4. Use git to create a diff, and pipe the output to a patch file: ```ShellSession $ git diff -a > nixpkgs/pkgs/the/package/0001-changes.patch ``` ## Deprecating/removing packages There is currently no policy when to remove a package. Before removing a package, one should try to find a new maintainer or fix smaller issues first. ### Steps to remove a package from Nixpkgs We use jbidwatcher as an example for a discontinued project here. 1. Have Nixpkgs checked out locally and up to date. 1. Create a new branch for your change, e.g. `git checkout -b jbidwatcher` 1. Remove the actual package including its directory, e.g. `git rm -rf pkgs/applications/misc/jbidwatcher` 1. Remove the package from the list of all packages (`pkgs/top-level/all-packages.nix`). 1. Add an alias for the package name in `pkgs/top-level/aliases.nix` (There is also `pkgs/applications/editors/vim/plugins/aliases.nix`. Package sets typically do not have aliases, so we can't add them there.) For example in this case: ```nix { jbidwatcher = throw "jbidwatcher was discontinued in march 2021"; # added 2021-03-15 } ``` The throw message should explain in short why the package was removed for users that still have it installed. 1. Test if the changes introduced any issues by running `nix-env -qaP -f . --show-trace`. It should show the list of packages without errors. 1. Commit the changes. Explain again why the package was removed. If it was declared discontinued upstream, add a link to the source. ```ShellSession $ git add pkgs/applications/misc/jbidwatcher/default.nix pkgs/top-level/all-packages.nix pkgs/top-level/aliases.nix $ git commit ``` Example commit message: ``` jbidwatcher: remove project was discontinued in march 2021. the program does not work anymore because ebay changed the login. https://web.archive.org/web/20210315205723/http://www.jbidwatcher.com/ ``` 1. Push changes to your GitHub fork with `git push` 1. Create a pull request against Nixpkgs. Mention the package maintainer. This is how the pull request looks like in this case: [https://github.com/NixOS/nixpkgs/pull/116470](https://github.com/NixOS/nixpkgs/pull/116470) ## Package tests To run the main types of tests locally: - Run package-internal tests with `nix-build --attr pkgs.PACKAGE.passthru.tests` - Run [NixOS tests](https://nixos.org/manual/nixos/unstable/#sec-nixos-tests) with `nix-build --attr nixosTests.NAME`, where `NAME` is the name of the test listed in `nixos/tests/all-tests.nix` - Run [global package tests](https://nixos.org/manual/nixpkgs/unstable/#sec-package-tests) with `nix-build --attr tests.PACKAGE`, where `PACKAGE` is the name of the test listed in `pkgs/test/default.nix` - See `lib/tests/NAME.nix` for instructions on running specific library tests Tests are important to ensure quality and make reviews and automatic updates easy. The following types of tests exists: * [NixOS **module tests**](https://nixos.org/manual/nixos/stable/#sec-nixos-tests), which spawn one or more NixOS VMs. They exercise both NixOS modules and the packaged programs used within them. For example, a NixOS module test can start a web server VM running the `nginx` module, and a client VM running `curl` or a graphical `firefox`, and test that they can talk to each other and display the correct content. * Nix **package tests** are a lightweight alternative to NixOS module tests. They should be used to create simple integration tests for packages, but cannot test NixOS services, and some programs with graphical user interfaces may also be difficult to test with them. * The **`checkPhase` of a package**, which should execute the unit tests that are included in the source code of a package.

This document outlines the procedures for removing packages from Nixpkgs and for running various types of package tests. For package removal, it provides a step-by-step guide, including creating a new git branch, removing package files and their entry from `all-packages.nix`, adding an alias to `aliases.nix` with a `throw` message explaining the removal reason, testing the changes, committing with a detailed message (including upstream discontinuation links if applicable), and creating a pull request. For package testing, it explains how to locally run package-internal tests, NixOS module tests (which involve VMs), global package tests, and library tests using `nix-build` commands. It further elaborates on the importance and characteristics of NixOS module tests, Nix package tests (as lightweight integration tests), and the `checkPhase` (for package-internal unit tests), emphasizing their role in ensuring quality and streamlining development.