Nixpkgs CI Build Triggers, Pull Request Behavior, and Package Category Guidelines

(using "→" instead of "->" is also accepted) Using the `(pkg-name):` prefix is important beyond just being a convention: it queues automatic builds by CI. More sophisticated prefixes are also possible: | Message | Automatic Builds | |--------------------------------------------------------------------------|------------------------------------------------------------| | `vim: 1.0.0 -> 2.0.0` | `vim` | | `vagrant: fix dependencies for version 2.0.2` | `vagrant` | | `python3{9,10}Packages.requests: 1.0.0 -> 2.0.0` | `python39Packages.requests`, `python310Packages.requests` | | `python312.pkgs.numpy,python313.pkgs.scipy: fix build` | `python312.pkgs.numpy` , `python313.pkgs.scipy` | When opening a PR with multiple commits, CI creates a single build job for all detected packages. If `passthru.tests` attributes are available, these will be built as well. If the title of the _PR_ begins with `WIP:` or contains `[WIP]` anywhere, its packages are not built automatically. Other than that, PR titles have meaning only for humans. It is recommended to keep the PR title in sync with the commit title, to make it easier to find. For PRs with multiple commits, the PR title should be a general summary of these commits. > [!NOTE] > Marking a PR as a draft does not prevent automatic builds. ## Category Hierarchy 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`. 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_:** - **If it’s a _library_ used by other packages:** - `development/libraries` (e.g. `libxml2`) - **If it’s a _compiler_:** - `development/compilers` (e.g. `gcc`) - **If it’s an _interpreter_:** - `development/interpreters` (e.g. `guile`) - **If it’s a (set of) development _tool(s)_:** - **If it’s a _parser generator_ (including lexers):** - `development/tools/parsing` (e.g. `bison`, `flex`) - **If it’s a _build manager_:** - `development/tools/build-managers` (e.g. `gnumake`) - **If it’s a _language server_:** - `development/tools/language-servers` (e.g. `ccls` or `nil`) - **Else:** - `development/tools/misc` (e.g. `binutils`) - **Else:** - `development/misc` **If it’s a (set of) _tool(s)_:** (A tool is a relatively small program, especially one intended to be used non-interactively.) - **If it’s for _networking_:** - `tools/networking` (e.g. `wget`) - **If it’s for _text processing_:** - `tools/text` (e.g. `diffutils`) - **If it’s a _system utility_, i.e., something related or essential to the operation of a system:** - `tools/system` (e.g. `cron`) - **If it’s an _archiver_ (which may include a compression function):** - `tools/archivers` (e.g. `zip`, `tar`) - **If it’s a _compression_ program:** - `tools/compression` (e.g. `gzip`, `bzip2`) - **If it’s a _security_-related program:**

This chunk details Nixpkgs commit conventions, explaining how `(pkg-name):` prefixes trigger automatic CI builds for single or multiple packages. It clarifies that PRs with multiple commits generate a single CI build job, including `passthru.tests`, and that `WIP:` in a PR title prevents automatic builds (draft PRs do not). The document then discusses the package category hierarchy, noting that `pkgs/by-name` is the preferred new standard, deprecating the older, loosely-categorized hierarchy. It provides rules for selecting the correct category within the older system, if alternate `callPackage` functions are needed, guiding users to classify packages by primary purpose into categories like `development/libraries`, `development/tools`, `tools/networking`, `tools/text`, `tools/system`, `tools/archivers`, `tools/compression`, and security-related programs.