Merge branch 'nixos-unstable' of https://github.com/NixOS/nixpkgs

1 files changed, 16 insertions, 0 deletions

diff --git a/nixpkgs/pkgs/by-name/README.md b/nixpkgs/pkgs/by-name/README.md
index fbdcfd7ecb79..ba1bd8cb9861 100644
--- a/nixpkgs/pkgs/by-name/README.md
+++ b/nixpkgs/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: