README.md: add FAQ

README.md

@@ -51,3 +51,28 @@ To use this binary cache, either run `cachix use ros` or manually set the follow
 substituters = https://cache.nixos.org https://ros.cachix.org
 trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= ros.cachix.org-1:dSyZxI8geDCJrwgvCOHDoAfOm5sV1wCPjBkKL+38Rvo=
 ```
+
+## Frequently Asked Questions
+
+**Q: Why are some packages missing?**
+
+A: All ROS packages published in the package index are potentially available in this overlay. If a package is missing, that probably means one of its system dependencies is not packaged. To determine the offending dependency, find the last "rosdistro sync" PR in this repository and search the missing dependencies list for your package's dependencies. In some cases, you may only need to add a mapping between the rosdep key and the nixpkgs attribute to the [rosdistro YAML files](https://github.com/lopsided98/rosdistro/tree/nixos-support/rosdep). If there is no Nix expression for the package, you should try to package it and submit it upstream to nixpkgs. In some cases it may be appropriate to add the package to this overlay instead, but this should be avoided if possible.
+
+**Q: Why do some packages fail to evaluate?**
+
+A: Some packages fail to evaluate with a error like the following:
+```
+at: (69:16) in file: /nix/store/7cy8wbxh0jmsy00219hi9pkrqm9lsh5j-source/lib/customisation.nix
+
+    68|     let
+    69|       result = f origArgs;
+      |                ^
+    70|
+
+anonymous function at nix-ros-overlay/distros/<distro>/<package>/default.nix:5:1 called without required argument '<dependency>'
+```
+This means all the system dependencies of `<package>` were available, so its Nix expression was generated, but some of `<dependency>`'s system dependencies were missing. See the question above for what to do next.
+
+**Q: Why do some packages fail to build?**
+
+There are thousands of ROS packages, so it is infeasible to make sure every package builds. I generally aim to keep at least 80-90% of the packages in a distribution successfully building, but this percentage tends to decrease as distributions get older and develop incompatibilities with newer software. If a package you need does not build, please open an issue or try to fix it yourself. In many cases, build failures occur due to bugs in the packages themselves, and should be fixed upstream. In other cases, overrides may need to be added to this overlay to fix the auto-generated expressions.