1 files changed, 69 insertions, 0 deletions
diff --git a/pkgs/README.md b/pkgs/README.md
index 4c736e658f093..8559d9bee0271 100644
--- a/pkgs/README.md
+++ b/pkgs/README.md
@@ -474,6 +474,53 @@ If you do need to do create this sort of patch file, one way to do so is with gi
     $ git diff -a > nixpkgs/pkgs/the/package/0001-changes.patch
     ```
 
+## 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 {#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:
+
+    ```
+    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)
+
 ## Testing changes | Package tests {#sec-package-tests}
 
 To run the main types of tests locally:
@@ -696,3 +743,25 @@ Sample template for a new package review is provided below.
 
 ##### Comments
 ```
+
+## (Security)
+
+### Submitting security fixes {#submitting-changes-submitting-security-fixes}
+
+Security fixes are submitted in the same way as other changes and thus the same guidelines apply.
+
+- If a new version fixing the vulnerability has been released, update the package;
+- If the security fix comes in the form of a patch and a CVE is available, then add the patch to the Nixpkgs tree, and apply it to the package.
+  The name of the patch should be the CVE identifier, so e.g. `CVE-2019-13636.patch`; If a patch is fetched the name needs to be set as well, e.g.:
+
+  ```nix
+  (fetchpatch {
+    name = "CVE-2019-11068.patch";
+    url = "https://gitlab.gnome.org/GNOME/libxslt/commit/e03553605b45c88f0b4b2980adfbbb8f6fca2fd6.patch";
+    hash = "sha256-SEKe/8HcW0UBHCfPTTOnpRlzmV2nQPPeL6HOMxBZd14=";
+  })
+  ```
+
+If a security fix applies to both master and a stable release then, similar to regular changes, they are preferably delivered via master first and cherry-picked to the release branch.
+
+Critical security fixes may by-pass the staging branches and be delivered directly to release branches such as `master` and `release-*`.