diff options
Diffstat (limited to 'doc')
4 files changed, 127 insertions, 4 deletions
diff --git a/doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua b/doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua index 92dc6895750f..1c745393a04b 100644 --- a/doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua +++ b/doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua @@ -27,6 +27,10 @@ function Code(elem) content = '<refentrytitle>' .. title .. '</refentrytitle>' .. (volnum ~= nil and ('<manvolnum>' .. volnum .. '</manvolnum>') or '') elseif elem.attributes['role'] == 'file' then tag = 'filename' + elseif elem.attributes['role'] == 'command' then + tag = 'command' + elseif elem.attributes['role'] == 'option' then + tag = 'option' end if tag ~= nil then diff --git a/doc/builders/images/dockertools.section.md b/doc/builders/images/dockertools.section.md index 458b0b36720f..d7f8741437cc 100644 --- a/doc/builders/images/dockertools.section.md +++ b/doc/builders/images/dockertools.section.md @@ -302,7 +302,7 @@ buildImage { runAsRoot = '' #!${pkgs.runtimeShell} - ${shadowSetup} + ${pkgs.dockerTools.shadowSetup} groupadd -r redis useradd -r -g redis redis mkdir /data diff --git a/doc/contributing/contributing-to-documentation.chapter.md b/doc/contributing/contributing-to-documentation.chapter.md index 1384772ebb2b..db16f13b474b 100644 --- a/doc/contributing/contributing-to-documentation.chapter.md +++ b/doc/contributing/contributing-to-documentation.chapter.md @@ -27,7 +27,7 @@ If the build succeeds, the manual will be in `./result/share/doc/nixpkgs/manual. As per [RFC 0072](https://github.com/NixOS/rfcs/pull/72), all new documentation content should be written in [CommonMark](https://commonmark.org/) Markdown dialect. -Additionally, the following syntax extensions are currently used: +Additional syntax extensions are available, though not all extensions can be used in NixOS option documentation. The following extensions are currently used: - []{#ssec-contributing-markup-anchors} Explicitly defined **anchors** on headings, to allow linking to sections. These should be always used, to ensure the anchors can be linked even when the heading text changes, and to prevent conflicts between [automatically assigned identifiers](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/auto_identifiers.md). @@ -53,12 +53,22 @@ Additionally, the following syntax extensions are currently used: This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/using/syntax.html#targets-and-cross-referencing). - []{#ssec-contributing-markup-inline-roles} - If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``, which will turn into {manpage}`nix.conf(5)`. + If you want to link to a man page, you can use `` {manpage}`nix.conf(5)` ``, which will turn into {manpage}`nix.conf(5)`. The references will turn into links when a mapping exists in {file}`doc/build-aux/pandoc-filters/link-unix-man-references.lua`. - The references will turn into links when a mapping exists in {file}`doc/build-aux/pandoc-filters/link-unix-man-references.lua`. + A few markups for other kinds of literals are also available: + + - `` {command}`rm -rfi` `` turns into {command}`rm -rfi` + - `` {option}`networking.useDHCP` `` turns into {option}`networking.useDHCP` + - `` {file}`/etc/passwd` `` turns into {file}`/etc/passwd` + + These literal kinds are used mostly in NixOS option documentation. This syntax is taken from [MyST](https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html#roles-an-in-line-extension-point). Though, the feature originates from [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-manpage) with slightly different syntax. + ::: {.note} + Inline roles are available for option documentation. + ::: + - []{#ssec-contributing-markup-admonitions} **Admonitions**, set off from the text to bring attention to something. @@ -84,6 +94,10 @@ Additionally, the following syntax extensions are currently used: - [`tip`](https://tdg.docbook.org/tdg/5.0/tip.html) - [`warning`](https://tdg.docbook.org/tdg/5.0/warning.html) + ::: {.note} + Admonitions are available for option documentation. + ::: + - []{#ssec-contributing-markup-definition-lists} [**Definition lists**](https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/definition_lists.md), for defining a group of terms: diff --git a/doc/contributing/reviewing-contributions.chapter.md b/doc/contributing/reviewing-contributions.chapter.md index 3417854730ef..4452695a6f38 100644 --- a/doc/contributing/reviewing-contributions.chapter.md +++ b/doc/contributing/reviewing-contributions.chapter.md @@ -185,6 +185,111 @@ Sample template for a new module review is provided below. ##### Comments ``` +## Individual maintainer list {#reviewing-contributions-indvidual-maintainer-list} + +When adding users to `maintainers/maintainer-list.nix`, the following +checks should be performed: + +- If the user has specified a GPG key, verify that the commit is + signed by their key. + + First, validate that the commit adding the maintainer is signed by + the key the maintainer listed. Check out the pull request and + compare its signing key with the listed key in the commit. + + If the commit is not signed or it is signed by a different user, ask + them to either recommit using that key or to remove their key + information. + + Given a maintainter entry like this: + + ``` nix + { + example = { + email = "user@example.com"; + name = "Example User"; + keys = [{ + fingerprint = "0000 0000 2A70 6423 0AED 3C11 F04F 7A19 AAA6 3AFE"; + }]; + } + }; + ``` + + First receive their key from a keyserver: + + $ gpg --recv-keys 0xF04F7A19AAA63AFE + gpg: key 0xF04F7A19AAA63AFE: public key "Example <user@example.com>" imported + gpg: Total number processed: 1 + gpg: imported: 1 + + Then check the commit is signed by that key: + + $ git log --show-signature + commit b87862a4f7d32319b1de428adb6cdbdd3a960153 + gpg: Signature made Wed Mar 12 13:32:24 2003 +0000 + gpg: using RSA key 000000002A7064230AED3C11F04F7A19AAA63AFE + gpg: Good signature from "Example User <user@example.com> + Author: Example User <user@example.com> + Date: Wed Mar 12 13:32:24 2003 +0000 + + maintainers: adding example + + and validate that there is a `Good signature` and the printed key + matches the user's submitted key. + + Note: GitHub's "Verified" label does not display the user's full key + fingerprint, and should not be used for validating the key matches. + +- If the user has specified a `github` account name, ensure they have + also specified a `githubId` and verify the two match. + + Maintainer entries that include a `github` field must also include + their `githubId`. People can and do change their GitHub name + frequently, and the ID is used as the official and stable identity + of the maintainer. + + Given a maintainer entry like this: + + ``` nix + { + example = { + email = "user@example.com"; + name = "Example User"; + github = "ghost"; + githubId = 10137; + } + }; + ``` + + First, make sure that the listed GitHub handle matches the author of + the commit. + + Then, visit the URL `https://api.github.com/users/ghost` and + validate that the `id` field matches the provided `githubId`. + +## Maintainer teams {#reviewing-contributions-maintainer-teams} + +Feel free to create a new maintainer team in `maintainers/team-list.nix` +when a group is collectively responsible for a collection of packages. +Use taste and personal judgement when deciding if a team is warranted. + +Teams are allowed to define their own rules about membership. + +For example, some teams will represent a business or other group which +wants to carefully track its members. Other teams may be very open about +who can join, and allow anybody to participate. + +When reviewing changes to a team, read the team's scope and the context +around the member list for indications about the team's membership +policy. + +In any case, request reviews from the existing team members. If the team +lists no specific membership policy, feel free to merge changes to the +team after giving the existing members a few days to respond. + +*Important:* If a team says it is a closed group, do not merge additions +to the team without an approval by at least one existing member. + ## Other submissions {#reviewing-contributions-other-submissions} Other type of submissions requires different reviewing steps. |