From 3cf87561dc1d3fa984ea697efbd44c2083e91337 Mon Sep 17 00:00:00 2001 From: Birdee <85372418+BirdeeHub@users.noreply.github.com> Date: Sat, 14 Mar 2026 19:14:59 -0700 Subject: [PATCH] chore(CONTRIBUTING.md): clarity --- CONTRIBUTING.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 22cd1a6..8b93b37 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -47,12 +47,11 @@ You may optionally set the `meta.description` option to provide a short descript ## Guidelines and Examples: -- When you provide an option to `enable` or `disable` something, you should call it `enable` regardless of its default value. -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. +When you provide an option to `enable` or `disable` something, you should call it `enable` regardless of its default value. -- 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. +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. -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. +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. 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. @@ -60,7 +59,9 @@ However, this makes the user of your module search for it, and in some situation 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. -- When you generate a file, it is generally better to do so as a string, and create it using the `constructFiles` option. +- Placeholders + +When you generate a file, it is generally better to do so as a string, and create it using the `constructFiles` option. This is because, this will make placeholders such as `${placeholder "out"}` work consistently across all your options. @@ -68,6 +69,8 @@ What this allows you to do, is manually build files later using `buildCommand` o 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. +It works by using `drv.passAsFile` and making a derivation attribute with the file contents, which is copied into place. + Example: ```nix @@ -195,11 +198,11 @@ For new additions, the description should be `init`, with any further explanatio Changes to helper modules should be titled `(modules.): some description`. For new additions, the description should be `init`, with any further explanation on subsequent lines -For `lib` additions and changes, the description should be `(lib..): some description` or `type(lib.): some description`. +For `lib` additions and changes, the description should be `(lib..): some description` or `(lib.): some description`. For template additions and changes, the description should be `(templates.): some description`. -Changes to the core options set defined in `lib/core.nix` should be titled `(core): some description`. +Changes to the core options set defined in `lib/core.nix` should be titled `(core.