pkgs/README.md: Update to mention pkgs/by-name

pkgs/README.md

@@ -7,7 +7,7 @@ See the [CONTRIBUTING.md](../CONTRIBUTING.md) document for more general informat
 
 - [`top-level`](./top-level): Entrypoints, package set aggregations
   - [`impure.nix`](./top-level/impure.nix), [`default.nix`](./top-level/default.nix), [`config.nix`](./top-level/config.nix): Definitions for the evaluation entry point of `import <nixpkgs>`
-  - [`stage.nix`](./top-level/stage.nix), [`all-packages.nix`](./top-level/all-packages.nix), [`splice.nix`](./top-level/splice.nix): Definitions for the top-level attribute set made available through `import <nixpkgs> {…}`
+  - [`stage.nix`](./top-level/stage.nix), [`all-packages.nix`](./top-level/all-packages.nix), [`by-name-overlay.nix`](./top-level/by-name-overlay.nix), [`splice.nix`](./top-level/splice.nix): Definitions for the top-level attribute set made available through `import <nixpkgs> {…}`
   - `*-packages.nix`, [`linux-kernels.nix`](./top-level/linux-kernels.nix), [`unixtools.nix`](./top-level/unixtools.nix): Aggregations of nested package sets defined in `development`
   - [`aliases.nix`](./top-level/aliases.nix), [`python-aliases.nix`](./top-level/python-aliases.nix): Aliases for package definitions that have been renamed or removed
   - `release*.nix`, [`make-tarball.nix`](./top-level/make-tarball.nix), [`packages-config.nix`](./top-level/packages-config.nix), [`metrics.nix`](./top-level/metrics.nix), [`nixpkgs-basic-release-checks.nix`](./top-level/nixpkgs-basic-release-checks.nix): Entry-points and utilities used by Hydra for continuous integration
@@ -19,6 +19,7 @@ See the [CONTRIBUTING.md](../CONTRIBUTING.md) document for more general informat
 - [`stdenv`](./stdenv): [Standard environment](https://nixos.org/manual/nixpkgs/stable/#part-stdenv)
 - [`pkgs-lib`](./pkgs-lib): Definitions for utilities that need packages but are not needed for packages
 - [`test`](./test): Tests not directly associated with any specific packages
+- [`by-name`](./by-name): Top-level packages organised by name ([docs](./by-name/README.md))
 - All other directories loosely categorise top-level packages definitions, see [category hierarchy][categories]
 
 ## Quick Start to Adding a Package
@@ -49,20 +50,23 @@ Now that this is out of the way. To add a package to Nixpkgs:
    $ cd nixpkgs
    ```
 
-2. Find a good place in the Nixpkgs tree to add the Nix expression for your package. For instance, a library package typically goes into `pkgs/development/libraries/pkgname`, while a web browser goes into `pkgs/applications/networking/browsers/pkgname`. See the [category hierarchy section][categories] for some hints on the tree organisation. Create a directory for your package, e.g.
+2. Create a package directory `pkgs/by-name/so/some-package` where `some-package` is the package name and `so` is the lowercased 2-letter prefix of the package name:
 
    ```ShellSession
-   $ mkdir pkgs/development/libraries/libfoo
+   $ mkdir -p pkgs/by-name/so/some-package
    ```
 
-3. In the package directory, create a Nix expression — a piece of code that describes how to build the package. In this case, it should be a _function_ that is called with the package dependencies as arguments, and returns a build of the package in the Nix store. The expression should usually be called `default.nix`.
+   For more detailed information, see [here](./by-name/README.md).
+
+3. Create a `package.nix` file in the package directory, containing a Nix expression — a piece of code that describes how to build the package. In this case, it should be a _function_ that is called with the package dependencies as arguments, and returns a build of the package in the Nix store.
 
    ```ShellSession
-   $ emacs pkgs/development/libraries/libfoo/default.nix
-   $ git add pkgs/development/libraries/libfoo/default.nix
+   $ emacs pkgs/by-name/so/some-package/package.nix
+   $ git add pkgs/by-name/so/some-package/package.nix
    ```
 
-   You can have a look at the existing Nix expressions under `pkgs/` to see how it’s done. Here are some good ones:
+   You can have a look at the existing Nix expressions under `pkgs/` to see how it’s done, some of which are also using the [category hierarchy](#category-hierarchy).
+   Here are some good ones:
 
    - GNU Hello: [`pkgs/applications/misc/hello/default.nix`](applications/misc/hello/default.nix). Trivial package, which specifies some `meta` attributes which is good practice.
 
@@ -94,21 +98,13 @@ Now that this is out of the way. To add a package to Nixpkgs:
 
    The exact syntax and semantics of the Nix expression language, including the built-in function, are [described in the Nix manual](https://nixos.org/manual/nix/stable/language/).
 
-4. Add a call to the function defined in the previous step to [`pkgs/top-level/all-packages.nix`](top-level/all-packages.nix) with some descriptive name for the variable, e.g. `libfoo`.
-
-   ```ShellSession
-   $ emacs pkgs/top-level/all-packages.nix
-   ```
-
-   The attributes in that file are sorted by category (like “Development / Libraries”) that more-or-less correspond to the directory structure of Nixpkgs, and then by attribute name.
-
 5. To test whether the package builds, run the following command from the root of the nixpkgs source tree:
 
    ```ShellSession
-   $ nix-build -A libfoo
+   $ nix-build -A some-package
    ```
 
-   where `libfoo` should be the variable name defined in the previous step. You may want to add the flag `-K` to keep the temporary build directory in case something fails. If the build succeeds, a symlink `./result` to the package in the Nix store is created.
+   where `some-package` should be the package name. You may want to add the flag `-K` to keep the temporary build directory in case something fails. If the build succeeds, a symlink `./result` to the package in the Nix store is created.
 
 6. If you want to install the package into your profile (optional), do
 
@@ -121,9 +117,19 @@ Now that this is out of the way. To add a package to Nixpkgs:
 ## Category Hierarchy
 [categories]: #category-hierarchy
 
-Each package should be stored in its own directory somewhere in the `pkgs/` tree, i.e. in `pkgs/category/subcategory/.../pkgname`. Below are some rules for picking the right category for a package. Many packages fall under several categories; what matters is the _primary_ purpose of a package. For example, the `libxml2` package builds both a library and some tools; but it’s a library foremost, so it goes under `pkgs/development/libraries`.
+Most top-level packages are organised in a loosely-categorised directory hierarchy in this directory.
+See the [overview](#overview) for which directories are part of this.
+
+This category hierarchy is partially deprecated and will be migrated away over time.
+The new `pkgs/by-name` directory ([docs](./by-name/README.md)) should be preferred instead.
+The category hierarchy may still be used for packages that should be imported using an alternate `callPackage`, such as `python3Packages.callPackage` or `libsForQt5.callPackage`.
 
-When in doubt, consider refactoring the `pkgs/` tree, e.g. creating new categories or splitting up an existing category.
+If that is the case for a new package, here are some rules for picking the right category.
+Many packages fall under several categories; what matters is the _primary_ purpose of a package.
+For example, the `libxml2` package builds both a library and some tools; but it’s a library foremost, so it goes under `pkgs/development/libraries`.
+
+<details>
+<summary>Categories</summary>
 
 **If it’s used to support _software development_:**
 
@@ -299,6 +305,8 @@ A (typically large) program with a distinct user interface, primarily used inter
 
 - `misc`
 
+</details>
+
 # Conventions
 
 ## Package naming