pyrox.dev
Merge pull request #272083 from tweag/lib-contrib
lib: Add contribution guidelines
authored by
Silvan Mosberger
and committed by
GitHub
0f8d175e
d2d00442
+63
lib/README.md
+63
lib/README.md
···
36
36
- [`options.nix`](options.nix): `lib.options` for anything relating to option definitions
37
37
- [`types.nix`](types.nix): `lib.types` for module system types
38
38
39
+
## PR Guidelines
40
+
41
+
Follow these guidelines for proposing a change to the interface of `lib`.
42
+
43
+
### Provide a Motivation
44
+
45
+
Clearly describe why the change is necessary and its use cases.
46
+
47
+
Make sure that the change benefits the user more than the added mental effort of looking it up and keeping track of its definition.
48
+
If the same can reasonably be done with the existing interface,
49
+
consider just updating the documentation with more examples and links.
50
+
This is also known as the [Fairbairn Threshold](https://wiki.haskell.org/Fairbairn_threshold).
51
+
52
+
Through this principle we avoid the human cost of duplicated functionality in an overly large library.
53
+
54
+
### Make one PR for each change
55
+
56
+
Don't have multiple changes in one PR, instead split it up into multiple ones.
57
+
58
+
This keeps the conversation focused and has a higher chance of getting merged.
59
+
60
+
### Name the interface appropriately
61
+
62
+
When introducing new names to the interface, such as new function, or new function attributes,
63
+
make sure to name it appropriately.
64
+
65
+
Names should be self-explanatory and consistent with the rest of `lib`.
66
+
If there's no obvious best name, include the alternatives you considered.
67
+
68
+
### Write documentation
69
+
70
+
Update the [reference documentation](#reference-documentation) to reflect the change.
71
+
72
+
Be generous with links to related functionality.
73
+
74
+
### Write tests
75
+
76
+
Add good test coverage for the change, including:
77
+
78
+
- Tests for edge cases, such as empty values or lists.
79
+
- Tests for tricky inputs, such as a string with string context or a path that doesn't exist.
80
+
- Test all code paths, such as `if-then-else` branches and returned attributes.
81
+
- If the tests for the sub-library are written in bash,
82
+
test messages of custom errors, such as `throw` or `abortMsg`,
83
+
84
+
At the time this is only not necessary for sub-libraries tested with [`tests/misc.nix`](./tests/misc.nix).
85
+
86
+
See [running tests](#running-tests) for more details on the test suites.
87
+
88
+
### Write tidy code
89
+
90
+
Name variables well, even if they're internal.
91
+
The code should be as self-explanatory as possible.
92
+
Be generous with code comments when appropriate.
93
+
94
+
As a baseline, follow the [Nixpkgs code conventions](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md#code-conventions).
95
+
96
+
### Write efficient code
97
+
98
+
Nix generally does not have free abstractions.
99
+
Be aware that seemingly straightforward changes can cause more allocations and a decrease in performance.
100
+
That said, don't optimise prematurely, especially in new code.
101
+
39
102
## Reference documentation
40
103
41
104
Reference documentation for library functions is written above each function as a multi-line comment.