You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+10-7Lines changed: 10 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -47,27 +47,30 @@ You may optionally set the `meta.description` option to provide a short descript
47
47
48
48
## Guidelines and Examples:
49
49
50
-
- When you provide an option to `enable` or `disable` something, you should call it `enable` regardless of its default value.
51
-
This prevents people from needing to look it up to use it, and prevents contributors from having to think too hard about which to call it.
50
+
When you provide an option to `enable` or `disable` something, you should call it `enable` regardless of its default value.
52
51
53
-
- When you provide a `wlib.types.file` option, you should name it the actual filename, especially if there are multiple, but `configFile` is also OK, especially if it is unambiguous.
52
+
This prevents people from needing to look it up to use it, and prevents contributors from having to think too hard about which to call it.
54
53
55
-
If you do name it `configFile` instead, you can fix the filenameif necessary/desired by setting `default.path` explicitly, as shown in the example below.
54
+
When you provide a `wlib.types.file` option, you should name it the actual filename, especially if there are multiple, but `configFile` is also OK, especially if it is unambiguous.
56
55
57
56
Keep in mind that even if you do not choose to use `wlib.types.file`, the user can usually still override the option that you set to provide the generated path if needed.
58
57
59
58
However, this makes the user of your module search for it, and in some situations, such as when your module is adding stuff to `list` or `DAL` type options, this can be slightly harder to override later.
60
59
61
60
So making use of the `wlib.types.file` type or giving some other method of overriding the filepath when providing a file is generally recommended for this reason.
62
61
63
-
- When you generate a file, it is generally better to do so as a string, and create it using the `constructFiles` option.
62
+
- Placeholders
63
+
64
+
When you generate a file, it is generally better to do so as a string, and create it using the `constructFiles` option.
64
65
65
66
This is because, this will make placeholders such as `${placeholder "out"}` work consistently across all your options.
66
67
67
68
What this allows you to do, is manually build files later using `buildCommand` option or a stdenv phase, and then refer to that created file within your settings!
68
69
69
70
Making placeholders work in your module makes your modules generally more easily extensible, and is preferred when it is possible to generate a usable string.
70
71
72
+
It works by using `drv.passAsFile` and making a derivation attribute with the file contents, which is copied into place.
73
+
71
74
Example:
72
75
73
76
```nix
@@ -195,11 +198,11 @@ For new additions, the description should be `init`, with any further explanatio
195
198
Changes to helper modules should be titled `<type>(modules.<name>): some description`.
196
199
For new additions, the description should be `init`, with any further explanation on subsequent lines
197
200
198
-
For `lib` additions and changes, the description should be `<type>(lib.<set>.<name>): some description` or `type(lib.<name>): some description`.
201
+
For `lib` additions and changes, the description should be `<type>(lib.<set>.<name>): some description` or `<type>(lib.<name>): some description`.
199
202
200
203
For template additions and changes, the description should be `<type>(templates.<name>): some description`.
201
204
202
-
Changes to the core options set defined in `lib/core.nix` should be titled `<type>(core): some description`.
205
+
Changes to the core options set defined in `lib/core.nix` should be titled `<type>(core.<option>): some description`.
203
206
204
207
`<type>` refers to a one word tag [like `feat`, `fix`, `docs`, or `test`](https://gist.github.com/Zekfad/f51cb06ac76e2457f11c80ed705c95a3#commit-types) as specified by [Conventional Commits](https://www.conventionalcommits.org)
0 commit comments