Merge pull request #272083 from tweag/lib-contrib
lib: Add contribution guidelines
This commit is contained in:
commit
0f8d175ebd
1 changed files with 63 additions and 0 deletions
|
@ -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.
|
||||
|
|
Loading…
Reference in a new issue