diff options
author | Alyssa Ross <hi@alyssa.is> | 2024-01-06 02:12:23 +0100 |
---|---|---|
committer | Alyssa Ross <hi@alyssa.is> | 2024-01-06 02:12:23 +0100 |
commit | f34a1b70eb86e4a63cfb88ea460345bb1aed88e3 (patch) | |
tree | 32834d23912250e0c4b86aa4420baacf8091c0fe /nixpkgs/lib/README.md | |
parent | 003ab91dd67b093890db1dd0bab564345db6e496 (diff) | |
parent | 7a7cfff8915e06365bc2365ff33d4d413184fa9f (diff) | |
download | nixlib-f34a1b70eb86e4a63cfb88ea460345bb1aed88e3.tar nixlib-f34a1b70eb86e4a63cfb88ea460345bb1aed88e3.tar.gz nixlib-f34a1b70eb86e4a63cfb88ea460345bb1aed88e3.tar.bz2 nixlib-f34a1b70eb86e4a63cfb88ea460345bb1aed88e3.tar.lz nixlib-f34a1b70eb86e4a63cfb88ea460345bb1aed88e3.tar.xz nixlib-f34a1b70eb86e4a63cfb88ea460345bb1aed88e3.tar.zst nixlib-f34a1b70eb86e4a63cfb88ea460345bb1aed88e3.zip |
Merge branch 'nixos-unstable-small' of https://github.com/NixOS/nixpkgs
Conflicts: nixpkgs/pkgs/build-support/go/module.nix
Diffstat (limited to 'nixpkgs/lib/README.md')
-rw-r--r-- | nixpkgs/lib/README.md | 63 |
1 files changed, 63 insertions, 0 deletions
diff --git a/nixpkgs/lib/README.md b/nixpkgs/lib/README.md index a886cf5bfb55..1cf10670ecb2 100644 --- a/nixpkgs/lib/README.md +++ b/nixpkgs/lib/README.md @@ -36,6 +36,69 @@ The [module system](https://nixos.org/manual/nixpkgs/#module-system) spans multi - [`options.nix`](options.nix): `lib.options` for anything relating to option definitions - [`types.nix`](types.nix): `lib.types` for module system types +## PR Guidelines + +Follow these guidelines for proposing a change to the interface of `lib`. + +### Provide a Motivation + +Clearly describe why the change is necessary and its use cases. + +Make sure that the change benefits the user more than the added mental effort of looking it up and keeping track of its definition. +If the same can reasonably be done with the existing interface, +consider just updating the documentation with more examples and links. +This is also known as the [Fairbairn Threshold](https://wiki.haskell.org/Fairbairn_threshold). + +Through this principle we avoid the human cost of duplicated functionality in an overly large library. + +### Make one PR for each change + +Don't have multiple changes in one PR, instead split it up into multiple ones. + +This keeps the conversation focused and has a higher chance of getting merged. + +### Name the interface appropriately + +When introducing new names to the interface, such as new function, or new function attributes, +make sure to name it appropriately. + +Names should be self-explanatory and consistent with the rest of `lib`. +If there's no obvious best name, include the alternatives you considered. + +### Write documentation + +Update the [reference documentation](#reference-documentation) to reflect the change. + +Be generous with links to related functionality. + +### Write tests + +Add good test coverage for the change, including: + +- Tests for edge cases, such as empty values or lists. +- Tests for tricky inputs, such as a string with string context or a path that doesn't exist. +- Test all code paths, such as `if-then-else` branches and returned attributes. +- If the tests for the sub-library are written in bash, + test messages of custom errors, such as `throw` or `abortMsg`, + + At the time this is only not necessary for sub-libraries tested with [`tests/misc.nix`](./tests/misc.nix). + +See [running tests](#running-tests) for more details on the test suites. + +### Write tidy code + +Name variables well, even if they're internal. +The code should be as self-explanatory as possible. +Be generous with code comments when appropriate. + +As a baseline, follow the [Nixpkgs code conventions](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md#code-conventions). + +### Write efficient code + +Nix generally does not have free abstractions. +Be aware that seemingly straightforward changes can cause more allocations and a decrease in performance. +That said, don't optimise prematurely, especially in new code. + ## Reference documentation Reference documentation for library functions is written above each function as a multi-line comment. |