maintainers/scripts/README.md

   1 # Maintainer scripts
   2
   3 This folder contains various executable scripts for nixpkgs maintainers,
   4 and supporting data or nixlang files as needed.
   5 These scripts generally aren't a stable interface and may changed or be removed.
   6
   7 What follows is a (very incomplete) overview of available scripts.
   8
   9
  10 ## Metadata
  11
  12 ### `get-maintainer.sh`
  13
  14 `get-maintainer.sh [selector] value` returns a JSON object describing
  15 a given nixpkgs maintainer, equivalent to `lib.maintainers.${x} // { handle = x; }`.
  16
  17 This allows looking up a maintainer's attrset (including GitHub and Matrix
  18 handles, email address etc.) based on any of their handles, more correctly and
  19 robustly than text search through `maintainers-list.nix`.
  20
  21 ```
  22 ❯ ./get-maintainer.sh nicoo
  23 {
  24   "email": "nicoo@debian.org",
  25   "github": "nbraud",
  26   "githubId": 1155801,
  27   "keys": [
  28     {
  29       "fingerprint": "E44E 9EA5 4B8E 256A FB73 49D3 EC9D 3708 72BC 7A8C"
  30     }
  31   ],
  32   "name": "nicoo",
  33   "handle": "nicoo"
  34 }
  35
  36 ❯ ./get-maintainer.sh name 'Silvan Mosberger'
  37 {
  38   "email": "contact@infinisil.com",
  39   "github": "infinisil",
  40   "githubId": 20525370,
  41   "keys": [
  42     {
  43       "fingerprint": "6C2B 55D4 4E04 8266 6B7D  DA1A 422E 9EDA E015 7170"
  44     }
  45   ],
  46   "matrix": "@infinisil:matrix.org",
  47   "name": "Silvan Mosberger",
  48   "handle": "infinisil"
  49 }
  50 ```
  51
  52 The maintainer is designated by a `selector` which must be one of:
  53 - `handle` (default): the maintainer's attribute name in `lib.maintainers`;
  54 - `email`, `name`, `github`, `githubId`, `matrix`, `name`:
  55   attributes of the maintainer's object, matched exactly;
  56   see [`maintainer-list.nix`] for the fields' definition.
  57
  58 [`maintainer-list.nix`]: ../maintainer-list.nix
  59
  60
  61 ## Conventions
  62
  63 ### `sha-to-sri.py`
  64
  65 `sha-to-sri.py path ...` (atomically) rewrites hash attributes (named `hash` or `sha(1|256|512)`)
  66 into the SRI format: `hash = "{hash name}-{base64 encoded value}"`.
  67
  68 `path` must point to either a nix file, or a directory which will be automatically traversed.
  69
  70 `sha-to-sri.py` automatically skips files whose first non-empty line contains `generated by` or `do not edit`.
  71 Moreover, when walking a directory tree, the script will skip files whose name is `yarn.nix` or contains `generated`.