doc: add instructions to remove a package

Co-authored-by: Sandro <sandro.jaeckel@gmail.com>
Co-authored-by: Ben Siraphob <bensiraphob@gmail.com>
This commit is contained in:
davidak 2021-03-15 22:47:40 +01:00
parent c00c67653a
commit c0b5d5bb9e

View file

@ -82,6 +82,52 @@ If a security fix applies to both master and a stable release then, similar to r
Critical security fixes may by-pass the staging branches and be delivered directly to release branches such as `master` and `release-*`. 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} ## 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. 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.