summary refs log tree commit diff
path: root/doc/contributing
diff options
context:
space:
mode:
authorSamuel Dionne-Riel <samuel@dionne-riel.com>2021-04-21 20:14:24 -0400
committerGitHub <noreply@github.com>2021-04-21 20:14:24 -0400
commit5ce39b7ee14bf02ad25c31d12f9b477808fecb3b (patch)
treebad48ebc4944a49be54d2272bf0bfd93488a05d2 /doc/contributing
parent92480267004b2bce95898371049c5162c64e4ae9 (diff)
parentc0b5d5bb9e857594b4b1f77be351e8bb4cec840f (diff)
downloadnixpkgs-5ce39b7ee14bf02ad25c31d12f9b477808fecb3b.tar
nixpkgs-5ce39b7ee14bf02ad25c31d12f9b477808fecb3b.tar.gz
nixpkgs-5ce39b7ee14bf02ad25c31d12f9b477808fecb3b.tar.bz2
nixpkgs-5ce39b7ee14bf02ad25c31d12f9b477808fecb3b.tar.lz
nixpkgs-5ce39b7ee14bf02ad25c31d12f9b477808fecb3b.tar.xz
nixpkgs-5ce39b7ee14bf02ad25c31d12f9b477808fecb3b.tar.zst
nixpkgs-5ce39b7ee14bf02ad25c31d12f9b477808fecb3b.zip
Merge pull request #116475 from davidak/doc-remove-packages
doc: add instructions to remove a package
Diffstat (limited to 'doc/contributing')
-rw-r--r--doc/contributing/submitting-changes.chapter.md46
1 files changed, 46 insertions, 0 deletions
diff --git a/doc/contributing/submitting-changes.chapter.md b/doc/contributing/submitting-changes.chapter.md
index 13f15b929cf..8a981284153 100644
--- a/doc/contributing/submitting-changes.chapter.md
+++ b/doc/contributing/submitting-changes.chapter.md
@@ -83,6 +83,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.