check-meta.nix: Add package warnings

doc/using/configuration.chapter.md

@@ -11,6 +11,8 @@ By default, Nix will prevent installation if any of the following criteria are t
 
 -   The package has known security vulnerabilities but has not or can not be updated for some reason, and a list of issues has been entered in to the package's `meta.knownVulnerabilities`.
 
+-   There are problems for packages which must be acknowledged, e.g. deprecation notices.
+
 Each of these criteria can be altered in the Nixpkgs configuration.
 
 :::{.note}
@@ -164,6 +166,57 @@ There are several ways to tweak how Nix handles a package which has been marked
 
     Note that `permittedInsecurePackages` is only checked if `allowInsecurePredicate` is not specified.
 
+## Packages with problems {#sec-problems}
+
+A package may have several problems associated with it.
+These can be either manually declared in `meta.problems`, or automatically generated from its other `meta` attributes.
+Each problem has a name, a "kind", a message, and optionally a list of URLs.
+Not all kinds can be manually specified in `meta.problems`, and some kinds can exist only up to once per package.
+Currently, the following problem kinds are known (with more reserved to be added in the future):
+
+- "removal": The package is planned to be removed some time in the future. Unique.
+- "deprecated": The package relies on software which has reached its end of life.
+- "maintainerless": Automatically generated for packages with `meta.maintainers == []`. Unique, not manually specifiable.
+
+Each problem has a handler that deals with it, which can be one of "error", "warn" or "ignore".
+"error" will disallow evaluating a package, while "warn" will simply print a message to the log.
+
+The handler for problems can be specified using `config.problems.handlers.${packageName}.${problemName} = "${handler}";`.
+
+There is also the possibility to specify some generic matchers, which can set a handler for more than a specific problem of a specific package.
+This works through the `config.problems.matchers` option:
+
+```nix
+{
+  problems.matchers = [
+    # Fail to build any packages which are about to be removed anyway
+    {
+      kind = "removal";
+      handler = "error";
+    }
+
+    # Get warnings when using packages with no declared maintainers
+    {
+      kind = "maintainerless";
+      handler = "warn";
+    }
+
+    # You deeply care about this package and want to absolutely know when it has any problems
+    {
+      package = "hello";
+      handler = "error";
+    }
+  ];
+}
+```
+
+Matchers can match one or more of package name, problem name or problem kind.
+If multiple conditions are present, all must be met to match.
+If multiple matchers match a problem, then the highest severity handler will be chosen.
+The current default value contains `{ kind = "removal"; handler = "error"; }`, meaning that people will be notified about package removals in advance.
+
+Package names for both `problems.handlers` and `problems.matchers` are taken from `lib.getName`, which looks at the `pname` first and falls back to extracting the "pname" part from the `name` attribute.
+
 ## Modify packages via `packageOverrides` {#sec-modify-via-packageOverrides}
 
 You can define a function called `packageOverrides` in your local `~/.config/nixpkgs/config.nix` to override Nix packages. It must be a function that takes pkgs as an argument and returns a modified set of packages.