Contributing Guidelines: Documentation, Testing, Code Quality, and Commit Conventions

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. These comments are processed using [nixdoc](https://github.com/nix-community/nixdoc) and [rendered in the Nixpkgs manual](https://nixos.org/manual/nixpkgs/stable/#chap-functions). The nixdoc README describes the [comment format](https://github.com/nix-community/nixdoc#comment-format). See [doc/README.md](../doc/README.md) for how to build the manual. ## Running tests All library tests can be run by building the derivation in [`tests/release.nix`](tests/release.nix): ```bash nix-build tests/release.nix ``` Some commands for quicker iteration over parts of the test suite are also available: ```bash # Run all evaluation unit tests in tests/misc.nix # if the resulting list is empty, all tests passed nix-instantiate --eval --strict tests/misc.nix # Run the module system tests tests/modules.sh # Run the lib.sources tests tests/sources.sh # Run the lib.filesystem tests tests/filesystem.sh # Run the lib.path property tests path/tests/prop.sh # Run the lib.fileset tests fileset/tests.sh ``` ## Commit conventions - Make sure you read about the [commit conventions](../CONTRIBUTING.md#commit-conventions) common to Nixpkgs as a whole. - Format the commit messages in the following way: ``` lib.(section): (init | add additional argument | refactor | etc) (Motivation for change. Additional information.) ``` Examples: * lib.getExe': check arguments * lib.fileset: Add an additional argument in the design docs Closes #264537

This document provides further guidelines for contributing to `lib`, covering several key areas. It instructs contributors to write comprehensive documentation above functions using nixdoc's multi-line comment format, which is then rendered in the Nixpkgs manual. It also emphasizes thorough test coverage, including edge cases, tricky inputs, and all code paths, with specific commands provided for running various parts of the test suite (e.g., `tests/release.nix`, `tests/misc.nix`, module tests). Regarding code quality, it advises on writing tidy, self-explanatory code with good variable names and comments, adhering to Nixpkgs code conventions, and considering code efficiency without premature optimization. Finally, it outlines commit conventions, requiring contributors to follow general Nixpkgs guidelines and use a specific format: `lib.(section): (summary)`.