diff --git a/doc/contributing/reviewing-contributions.chapter.md b/doc/contributing/reviewing-contributions.chapter.md index 3417854730e..4452695a6f3 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 " 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 + Author: Example User + 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.