From c0b5d5bb9e857594b4b1f77be351e8bb4cec840f Mon Sep 17 00:00:00 2001 From: davidak Date: Mon, 15 Mar 2021 22:47:40 +0100 Subject: [PATCH] doc: add instructions to remove a package Co-authored-by: Sandro Co-authored-by: Ben Siraphob --- .../submitting-changes.chapter.md | 46 +++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/doc/contributing/submitting-changes.chapter.md b/doc/contributing/submitting-changes.chapter.md index 44e981f12a53a..5293e104a3768 100644 --- a/doc/contributing/submitting-changes.chapter.md +++ b/doc/contributing/submitting-changes.chapter.md @@ -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-*`. +## 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.