lib: Make `overrideScope'` which takes arguments in the conventional order

The `overrideScope` bound by `makeScope` (via special `callPackage`)
took an override in the form `super: self { … }`. But this is
dangerously close to the `self: super { … }` form used by *everything*
else, even other definitions of `overrideScope`! Since that
implementation did not even share any code either until I changed it
recently in 3cf43547f4be03d1d6eb0bbfc557e2dbc13b4095, this inconsistency
is almost certainly an oversight and not intentional.

Unfortunately, just as the inconstency is hard to debug if one just
assumes the conventional order, any sudden fix would break existing
overrides in the same hard-to-debug way. So instead of changing the
definition a new `overrideScope'` with the conventional order is added,
and old `overrideScope` deprecated with a warning saying to use
`overrideScope'` instead. That will hopefully get people to stop using
`overrideScope`, freeing our hand to change or remove it in the future.

1 files changed, 3 insertions, 3 deletions

diff --git a/doc/package-notes.xml b/doc/package-notes.xml
index c2aef8937b06..7b8657fb4a13 100644
--- a/doc/package-notes.xml
+++ b/doc/package-notes.xml
@@ -643,15 +643,15 @@ cp ${myEmacsConfig} $out/share/emacs/site-lisp/default.el
     required dependencies manually - but it's tedious and there is always a
     possibility that an unwanted dependency will sneak in through some other
     package. To completely override such a package you can use
-    <varname>overrideScope</varname>.
+    <varname>overrideScope'</varname>.
    </para>
 
 <screen>
-overrides = super: self: rec {
+overrides = self: super: rec {
   haskell-mode = self.melpaPackages.haskell-mode;
   ...
 };
-((emacsPackagesNgGen emacs).overrideScope overrides).emacsWithPackages (p: with p; [
+((emacsPackagesNgGen emacs).overrideScope' overrides).emacsWithPackages (p: with p; [
   # here both these package will use haskell-mode of our own choice
   ghc-mod
   dante