How to interpret "NOTE" in Nixpkgs manual about overlays?

[toraritte]

I set out to understand overlays, but found the following part in the Set overlays in NixOS or Nix expressions confusing (especially because I never even used one):

The list of overlays can be passed explicitly when importing nixpkgs, for example import <nixpkgs> { overlays = [ overlay1 overlay2 ]; }.

NOTE: DO NOT USE THIS in nixpkgs. Further overlays can be added by calling the pkgs.extend or pkgs.appendOverlays, although it is often preferable to avoid these functions, because they recompute the Nixpkgs fixpoint, which is somewhat expensive to do.

Does the note warn against declaring overlays with import or using the extend / appendOverlays functions?

[rhendric]

The latter; see this PR.

But that note isn’t relevant unless you’re writing code in Nixpkgs.

[das-g]

Should we rephrase that to

The list of overlays can be passed explicitly when importing nixpkgs, for example import <nixpkgs> { overlays = [ overlay1 overlay2 ]; }.

NOTE: DO NOT USE pkgs.extend or pkgs.appendOverlays in nixpkgs. Further overlays can be added by calling the pkgs.extend or pkgs.appendOverlays, although it is often preferable to avoid these functions, because they recompute the Nixpkgs fixpoint, which is somewhat expensive to do.

to make it unambiguous?

(And should this maybe be formatted as an admonition?)

[waffle8946]

We’re trending in the direction to remove instructions for “how to contribute to nixpkgs” from the nixpkgs manual, since such instructions are better suited to the contribution guidelines and directory-specific readmes.