I recently ended up spending many hours tracking down a very weird, non-deterministic bug on some of my systems, involving import-from-derivation, which in the end turned out to be caused by passing sources.some-package as a src argument to a derivation.

From niv's minimal documentation, I'd been assuming that the sources attribute mapped names to either paths or derivations, but instead it maps names to weird pseudo-derivation attribute sets constructed by explicitly setting outPath. As it turns out, from a broader Nix perspective this is an undocumented hack that breaks in a bunch of places (including as previously noted, when used with Hydra).

So, to save future users some time, effort, and pain, I recommend some subset of the following (at least the first!):

1. Updating the documentation to recommend using sources.package.outPath instead.
2. Document the fact that the spec attributes are available in sources values, because this is potentially very useful for some users.
3. Document the ability to use the sources functor to override the pkgs and system used internally; this also would have been great to know about previously, for usage with flakes.
4. Consider renaming outPath to something else so as to force people to be explicit about this. Yes, it's marginally less convenient, but it is going to save you from shooting yourself in the foot at some far-distant point... which is very much in the spirit of Nix no?