Merge pull request #116475 from davidak/doc-remove-packages

Critical security fixes may by-pass the staging branches and be delivered directly to release branches such as `master` and `release-*`.

## Deprecating/removing packages {#submitting-changes-deprecating-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. `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/misc/vim-plugins/aliases.nix`. Package sets typically do not have aliases, so we can't add them there.)

    For example in this case:

    ```

    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)

## Pull Request Template {#submitting-changes-pull-request-template}

The pull request template helps determine what steps have been made for a contribution so far, and will help guide maintainers on the status of a change. The motivation section of the PR should include any extra details the title does not address and link any existing issues related to the pull request.