Merge pull request #272083 from tweag/lib-contrib

lib: Add contribution guidelines
This commit is contained in:
Silvan Mosberger 2023-12-19 22:29:51 +01:00 committed by GitHub
commit 0f8d175ebd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -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.