docs: update contribution guidelines
Some checks failed
Set up binary cache / cachix (default) (push) Has been cancelled
Set up binary cache / cachix (maximal) (push) Has been cancelled
Set up binary cache / cachix (nix) (push) Has been cancelled
Validate flake & check documentation / Validate Flake Documentation (docs) (push) Has been cancelled
Validate flake & check documentation / Validate Flake Documentation (docs-html) (push) Has been cancelled
Validate flake & check documentation / Validate Flake Documentation (docs-json) (push) Has been cancelled
Validate flake & check documentation / Validate Flake Documentation (docs-manpages) (push) Has been cancelled
Validate flake & check documentation / Validate hyperlinks in documentation sources (push) Has been cancelled
Validate flake & check formatting / Validate Flake (push) Has been cancelled
Validate flake & check formatting / Formatting via Alejandra (push) Has been cancelled
Build and deploy documentation / Check latest commit (push) Has been cancelled
Check for typos in the source tree / check-typos (push) Has been cancelled
Build and deploy documentation / publish (push) Has been cancelled

Update URL for nixpkgs flavoured markdown, add mkOption argument ordering
This commit is contained in:
raf 2025-01-14 16:01:56 +03:00
parent 4b9047025f
commit 9142a5b9dd
No known key found for this signature in database
GPG key ID: EED98D11B85A2819

View file

@ -14,14 +14,11 @@ necessarily) before you start developing.
## Adding Documentation {#sec-guidelines-documentation} ## Adding Documentation {#sec-guidelines-documentation}
Most, if not all, changes warrant changes to the documentation. Module options [Nixpkgs Flavoured Markdown]: https://github.com/NixOS/nixpkgs/blob/master/doc/README.md#syntax
should be documented with
[Nixpkgs-flavoured Markdown](https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup),
albeit with exceptions.
::: {.note} As of **v0.5**, **nvf** is itself documented using full markdown in Almost all changes warrant updates to the documentation: at the very least, you
both module options and the manual. With **v0.6**, this manual has also been must update the changelog. Both the manual and module options use
converted to markdown in full. ::: [Nixpkgs Flavoured Markdown].
The HTML version of this manual containing both the module option descriptions The HTML version of this manual containing both the module option descriptions
and the documentation of **nvf** (such as this page) can be generated and opened and the documentation of **nvf** (such as this page) can be generated and opened
@ -117,10 +114,11 @@ applies to string literals and module descriptions and documentation.
### Nix {#sec-code-style-nix} ### Nix {#sec-code-style-nix}
**nvf** is formatted by the [alejandra]: https://github.com/kamadorueda/alejandra
[alejandra](https://github.com/kamadorueda/alejandra) tool and the formatting is
checked in the pull request and push workflows. Run the `nix fmt` command inside **nvf** is formatted by the [alejandra] tool and the formatting is checked in
the project repository before submitting your pull request. the pull request and push workflows. Run the `nix fmt` command inside the
project repository before submitting your pull request.
While Alejandra is mostly opinionated on how code looks after formatting, While Alejandra is mostly opinionated on how code looks after formatting,
certain changes are done at the user's discretion based on how the original code certain changes are done at the user's discretion based on how the original code
@ -138,10 +136,14 @@ module = {
# same as parent modules, unfold submodules # same as parent modules, unfold submodules
subModule = { subModule = {
# this is an option that contains more than one nested value # this is an option that contains more than one nested value
# Note: try to be careful about the ordering of `mkOption` arguments.
# General rule of thumb is to order from least to most likely to change.
# This is, for most cases, type < default < description.
# Example, if present, would be between default and description
someOtherValue = mkOption { someOtherValue = mkOption {
type = lib.types.bool; type = lib.types.bool;
description = "Some other description";
default = true; default = true;
description = "Some other description";
}; };
}; };
} }