From 6857dc8712c345f804cf87ffc0324e6f361364ec Mon Sep 17 00:00:00 2001 From: Doron Behar Date: Thu, 7 Aug 2025 11:22:13 +0300 Subject: [PATCH] pkgs/README: Document commit prefixes & automatic CI builds Somewhat based upon ofborg's README contents: https://github.com/NixOS/ofborg?tab=readme-ov-file#automatic-building Co-authored-by: Wolfgang Walther Co-authored-by: Peder Bergebakken Sundt --- pkgs/README.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/pkgs/README.md b/pkgs/README.md index 14a4fc355fb5..7dd549cc3438 100644 --- a/pkgs/README.md +++ b/pkgs/README.md @@ -187,6 +187,27 @@ To add a package to Nixpkgs: (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 [categories]: #category-hierarchy