From e27e30204b9c77f2b1650c4dad80f100b44b2dfb Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 12 Sep 2023 00:18:09 +0200 Subject: [PATCH] pkgs/by-name: Add manual migration guidelines Motivated from seeing people starting to migrate packages manually when it shouldn't be necessary or done differently. --- pkgs/by-name/README.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/pkgs/by-name/README.md b/pkgs/by-name/README.md index fbdcfd7ecb79..ba1bd8cb9861 100644 --- a/pkgs/by-name/README.md +++ b/pkgs/by-name/README.md @@ -72,6 +72,22 @@ libfoo = callPackage ../by-name/so/some-package/package.nix { }; ``` +## Manual migration guidelines + +Most packages are still defined in `all-packages.nix` and the [category hierarchy](../README.md#category-hierarchy). +Please hold off migrating your maintained packages to this directory. + +1. An automated migration for the majority of packages [is being worked on](https://github.com/NixOS/nixpkgs/pull/211832). + In order to save on contributor and reviewer time, packages should only be migrated manually afterwards if they couldn't be migrated automatically. + +1. Manual migrations should only be lightly encouraged if the relevant code is being worked on anyways. + For example with a package update or refactoring. + +1. Manual migrations should not remove definitions from `all-packages.nix` with custom arguments. + That is a backwards-incompatible change because it changes the `.override` interface. + Such packages may still be moved to `pkgs/by-name` however, while keeping the definition in `all-packages.nix`. + See also [changing implicit attribute defaults](#changing-implicit-attribute-defaults). + ## Limitations There's some limitations as to which packages can be defined using this structure: