Skip to content

Commit e43f7cf

Browse files
authored
chore(CONTRIBUTING.md): clarity (#341)
1 parent d4a13a9 commit e43f7cf

1 file changed

Lines changed: 10 additions & 7 deletions

File tree

CONTRIBUTING.md

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -47,27 +47,30 @@ You may optionally set the `meta.description` option to provide a short descript
4747

4848
## Guidelines and Examples:
4949

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

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

55-
If you do name it `configFile` instead, you can fix the filename if 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.
5655

5756
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.
5857

5958
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.
6059

6160
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.
6261

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

6566
This is because, this will make placeholders such as `${placeholder "out"}` work consistently across all your options.
6667

6768
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!
6869

6970
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.
7071

72+
It works by using `drv.passAsFile` and making a derivation attribute with the file contents, which is copied into place.
73+
7174
Example:
7275

7376
```nix
@@ -195,11 +198,11 @@ For new additions, the description should be `init`, with any further explanatio
195198
Changes to helper modules should be titled `<type>(modules.<name>): some description`.
196199
For new additions, the description should be `init`, with any further explanation on subsequent lines
197200

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`.
199202

200203
For template additions and changes, the description should be `<type>(templates.<name>): some description`.
201204

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`.
203206

204207
`<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)
205208

0 commit comments

Comments
 (0)