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