doc: add instructions to rename a package

[davidak]

Issue description

how to handle a renamed package?

currently there are examples in nixpkgs that add an alias, but also throw an error with "was renamed to X"

https://github.com/NixOS/nixpkgs/blob/master/pkgs/top-level/aliases.nix#L53

which is better UX? maybe it should work like options aliases? (warn on rebuild)

when there is a consensus, i can document it, as done with #116475 (but feel free to grab the task if you like)

Steps to reproduce

this topic came up in #141264 (comment)

[stale]

I marked this as stale due to inactivity. → More info

[davidak]

For renaming modules there exist mkRenamedOptionModule which prints a warning like this in a nixos-rebuild:

trace: warning: The option `fonts.enableFontDir' defined in `/root/nixos/services/fonts' has been renamed to `fonts.fontDir.enable'.

that is a good user experience since it continues to work, but they are warned that they should update their config.

We need something similar for packages!

The code of mkRenamedOptionModule:

/* Return a module that causes a warning to be shown if the
   specified "from" option is defined; the defined value is however
   forwarded to the "to" option. This can be used to rename options
   while providing backward compatibility. For example,

     mkRenamedOptionModule [ "boot" "copyKernels" ] [ "boot" "loader" "grub" "copyKernels" ]

   forwards any definitions of boot.copyKernels to
   boot.loader.grub.copyKernels while printing a warning.

   This also copies over the priority from the aliased option to the
   non-aliased option.
*/
mkRenamedOptionModule = from: to: doRename {
  inherit from to;
  visible = false;
  warn = true;
  use = builtins.trace "Obsolete option `${showOption from}' is used. It was renamed to `${showOption to}'.";
};

mkRenamedOptionModuleWith = {
  /* Old option path as list of strings. */
  from,
  /* New option path as list of strings. */
  to,

  /*
    Release number of the first release that contains the rename, ignoring backports.
    Set it to the upcoming release, matching the nixpkgs/.version file.
  */
  sinceRelease,

}: doRename {
  inherit from to;
  visible = false;
  warn = lib.isInOldestRelease sinceRelease;
  use = lib.warnIf (lib.isInOldestRelease sinceRelease)
    "Obsolete option `${showOption from}' is used. It was renamed to `${showOption to}'.";
};

doRename = { from, to, visible, warn, use, withPriority ? true }:
  { config, options, ... }:
  let
    fromOpt = getAttrFromPath from options;
    toOf = attrByPath to
      (abort "Renaming error: option `${showOption to}' does not exist.");
    toType = let opt = attrByPath to {} options; in opt.type or (types.submodule {});
  in
  {
    options = setAttrByPath from (mkOption {
      inherit visible;
      description = "Alias of <option>${showOption to}</option>.";
      apply = x: use (toOf config);
    } // optionalAttrs (toType != null) {
      type = toType;
    });
    config = mkMerge [
      {
        warnings = optional (warn && fromOpt.isDefined)
          "The option `${showOption from}' defined in ${showFiles fromOpt.files} has been renamed to `${showOption to}'.";
      }
      (if withPriority
        then mkAliasAndWrapDefsWithPriority (setAttrByPath to) fromOpt
        else mkAliasAndWrapDefinitions (setAttrByPath to) fromOpt)
    ];
  };

So here is some unfinished code:

/*

example:

mkRenamedPackage piwik matomo; # added 2018-01-16

*/
mkRenamedPackage = from: to: {
  inherit from to;
  visible = false;
  warnings = "The package `${from}' defined in ${showFiles fromOpt.files} was renamed to `${to}'. Please use the new name.";
  from = to;
};

Can someone complete it? I'm not experienced enough with nixlang for it.

[davidak]

@ckiee could that be implemented similar to #170992?

Those packages have no metadata indicating that they are renamed. Could that be interpolated or added in some way when we have the alias definitions in a renamed.nix file in kgs/top-level/?

So:

<some magic code>

badtouch = authoscope; # Project was renamed, added 20210626
bro = zeek; # Added 2019-09-29
codimd = hedgedoc; # Added 2020-11-29
...

</some magic code>

[ckiee]

@davidak sure, but interpreting comments probably wouldn't be very nice. You could write a little wrapper around builtins.trace like this:

mkRename = old: new: date: builtins.trace "${old.pname} was renamed to ${new.pname} on ${date} and the old name is now deprecated and will be removed in a future release"

Some more code missing there that I haven't bothered to write, but I'll probably make a PR for this eventually, got a lot of stuff to work on at the moment.

[davidak]

Awesome! When we have the general infrastructure to do it i can add the packages, so you can do more meaningful work.

[ckiee]

Awesome! When we have the general infrastructure to do it i can add the packages, so you can do more meaningful work.

the work is equally meaningful, it's just a matter of different skillsets I guess ❤️

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/how-to-introduce-a-breaking-version-bump/46746/9