From 1d7f14656a699e61e549f16e8e3e406241a31c87 Mon Sep 17 00:00:00 2001 From: nicoo Date: Fri, 8 Dec 2023 02:57:38 +0100 Subject: maintainers-list.nix: Document (current) invitation process, add get-maintainer.sh (#267084) * maintainer-list: Document automatic invites to @NixOS/nixpkgs-maintainers * maintainers/scripts: Add `get-maintainer.sh` Supports querying `maintainers-list.nix` by Nix attribute, email address, github name or id, matrix account, or name. * maintainers/scripts/get-maintainer.sh: More verbose help message * maintainers/scripts/get-maintainer.sh: Fix (some) `shellcheck` lints * maintainers/scripts: Add README * maintainers/scripts/get-maintainer.sh: Put inline documentation at the top of the file * maintainers/scripts: Document this is not a stable interfact to nixpkgs Co-authored-by: Silvan Mosberger * scripts/README: Add example for `get-maintainer.sh` --------- Co-authored-by: Silvan Mosberger --- maintainers/README.md | 7 ++++ maintainers/maintainer-list.nix | 6 ++- maintainers/scripts/README.md | 58 ++++++++++++++++++++++++++++ maintainers/scripts/get-maintainer.sh | 73 +++++++++++++++++++++++++++++++++++ 4 files changed, 142 insertions(+), 2 deletions(-) create mode 100644 maintainers/scripts/README.md create mode 100755 maintainers/scripts/get-maintainer.sh (limited to 'maintainers') diff --git a/maintainers/README.md b/maintainers/README.md index 5bb9c58db024..f121ec756413 100644 --- a/maintainers/README.md +++ b/maintainers/README.md @@ -165,3 +165,10 @@ 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. + + +# Maintainer scripts + +Various utility scripts, which are mainly useful for nixpkgs maintainers, +are available under `./scripts/`. See its [README](./scripts/README.md) +for further information. diff --git a/maintainers/maintainer-list.nix b/maintainers/maintainer-list.nix index c5ff33f5dd17..542e58ff33ce 100644 --- a/maintainers/maintainer-list.nix +++ b/maintainers/maintainer-list.nix @@ -26,8 +26,10 @@ - `githubId` is your GitHub user ID, which can be found at `https://api.github.com/users/`, - `keys` is a list of your PGP/GPG key fingerprints. - Specifying a GitHub account ensures that you automatically get a review request on - pull requests that modify a package for which you are a maintainer. + Specifying a GitHub account ensures that you automatically: + - get invited to the @NixOS/nixpkgs-maintainers team ; + - once you are part of the @NixOS org, OfBorg will request you review + pull requests that modify a package for which you are a maintainer. `handle == github` is strongly preferred whenever `github` is an acceptable attribute name and is short and convenient. diff --git a/maintainers/scripts/README.md b/maintainers/scripts/README.md new file mode 100644 index 000000000000..2b99a4e75114 --- /dev/null +++ b/maintainers/scripts/README.md @@ -0,0 +1,58 @@ +# Maintainer scripts + +This folder contains various executable scripts for nixpkgs maintainers, +and supporting data or nixlang files as needed. +These scripts generally aren't a stable interface and may changed or be removed. + +What follows is a (very incomplete) overview of available scripts. + + +## Metadata + +### `get-maintainer.sh` + +`get-maintainer.sh [selector] value` returns a JSON object describing +a given nixpkgs maintainer, equivalent to `lib.maintainers.${x} // { handle = x; }`. + +This allows looking up a maintainer's attrset (including GitHub and Matrix +handles, email address etc.) based on any of their handles, more correctly and +robustly than text search through `maintainers-list.nix`. + +``` +❯ ./get-maintainer.sh nicoo +{ + "email": "nicoo@debian.org", + "github": "nbraud", + "githubId": 1155801, + "keys": [ + { + "fingerprint": "E44E 9EA5 4B8E 256A FB73 49D3 EC9D 3708 72BC 7A8C" + } + ], + "name": "nicoo", + "handle": "nicoo" +} + +❯ ./get-maintainer.sh name 'Silvan Mosberger' +{ + "email": "contact@infinisil.com", + "github": "infinisil", + "githubId": 20525370, + "keys": [ + { + "fingerprint": "6C2B 55D4 4E04 8266 6B7D DA1A 422E 9EDA E015 7170" + } + ], + "matrix": "@infinisil:matrix.org", + "name": "Silvan Mosberger", + "handle": "infinisil" +} +``` + +The maintainer is designated by a `selector` which must be one of: +- `handle` (default): the maintainer's attribute name in `lib.maintainers`; +- `email`, `name`, `github`, `githubId`, `matrix`, `name`: + attributes of the maintainer's object, matched exactly; + see [`maintainer-list.nix`] for the fields' definition. + +[`maintainer-list.nix`]: ../maintainer-list.nix diff --git a/maintainers/scripts/get-maintainer.sh b/maintainers/scripts/get-maintainer.sh new file mode 100755 index 000000000000..3061d2ccc72f --- /dev/null +++ b/maintainers/scripts/get-maintainer.sh @@ -0,0 +1,73 @@ +#!/usr/bin/env nix-shell +#!nix-shell -i bash -p jq ncurses +# shellcheck shell=bash + +# Get a nixpkgs maintainer's metadata as a JSON object +# see HELP_MESSAGE just below, or README.md. + +set -euo pipefail + +declare -A SELECTORS=( [handle]= [email]= [github]= [githubId]= [matrix]= [name]= ) +HELP_MESSAGE="usage: '$0' [selector] value +examples: + get-maintainer.sh nicoo + get-maintainer.sh githubId 1155801 + +\`selector\` defaults to 'handle', can be one of: + ${!SELECTORS[*]} +" + +MAINTAINERS_DIR="$(dirname "$0")/.." + +die() { + tput setaf 1 # red + echo "'$0': $*" + tput setaf 0 # back to black + exit 1 +} + +listAsJSON() { + nix-instantiate --eval --strict --json "${MAINTAINERS_DIR}/maintainer-list.nix" +} + +parseArgs() { + [ $# -gt 0 -a $# -lt 3 ] || { + echo "$HELP_MESSAGE" + die "invalid number of arguments (must be 1 or 2)" + } + + if [ $# -eq 1 ]; then + selector=handle + else + selector="$1" + shift + fi + [ -z "${SELECTORS[$selector]-n}" ] || { + echo "Valid selectors are:" "${!SELECTORS[@]}" >&2 + die "invalid selector '$selector'" + } + + value="$1" + shift +} + +query() { + # explode { a: A, b: B, ... } into A + {handle: a}, B + {handle: b}, ... + local explode="to_entries[] | .value + { \"handle\": .key }" + + # select matching items from the list + # TODO(nicoo): Support approximate matching for `name` ? + local select + case "$selector" in + githubId) + select="select(.${selector} == $value)" + ;; + *) + select="select(.${selector} == \"$value\")" + esac + + echo "$explode | $select" +} + +parseArgs "$@" +listAsJSON | jq -e "$(query)" -- cgit 1.4.1