Update documentation.

Update the page on repository metrics to reflect the recent changes in Markdown output and in the accepted syntax of the `user` and `team` selectors.
gouttegd · Jul 10, 2023 · 29b154a · 29b154a
1 parent 9e758d3
commit 29b154a
Showing 1 changed file with 85 additions and 54 deletions.
diff --git a/docs/metrics.rst b/docs/metrics.rst
@@ -48,17 +48,17 @@ Here is an example of a default report:
    $ grainyhead metrics
    From 2021-09-02 to 2021-12-01
    
-   | Event                | Total | Internal | Inte (%) | External | Exte (%) |
-   | -------------------- | ----- | -------- | -------- | -------- | -------- |
-   | Contributors         |    24 |       15 |    62.50 |        9 |    37.50 |
-   | Issues opened        |    71 |       64 |    90.14 |        7 |     9.86 |
-   | Issues closed        |    89 |       77 |    86.52 |       12 |    13.48 |
-   | Pull requests opened |    86 |       68 |    79.07 |       18 |    20.93 |
-   | Pull requests closed |    94 |       78 |    82.98 |       16 |    17.02 |
-   | Pull requests merged |    79 |       65 |    82.28 |       14 |    17.72 |
-   | Comments             |   476 |      412 |    86.55 |       64 |    13.45 |
-   | Commits              |   232 |      201 |    86.64 |       31 |    13.36 |
-   | Releases             |     4 |        4 |   100.00 |        0 |     0.00 |
+   | Event | Total | Internal | Internal (%) | External | External (%) |
+   | -------- | ----- | -------- | -------- | -------- | -------- |
+   | Contributors | 24 | 15 | 62.50 | 9 | 37.50 |
+   | Issues opened | 71 | 64 | 90.14 | 7 | 9.86 |
+   | Issues closed | 89 | 77 | 86.52 | 12 | 13.48 |
+   | Pull requests opened | 86 | 68 | 79.07 | 18 | 20.93 |
+   | Pull requests closed | 94 | 78 | 82.98 | 16 | 17.02 |
+   | Pull requests merged | 79 | 65 | 82.28 | 14 | 17.72 |
+   | Comments | 476 | 412 | 86.55 | 64 | 13.45 |
+   | Commits | 232 | 201 | 86.64 | 31 | 13.36 |
+   | Releases | 4 | 4 | 100.00 | 0 | 0.00 |
 
 This report indicates, for example, that 24 users contributed to the repository
 between September 2nd, 2021 and December 1st, 2021; 15 of them (62.5%) were
@@ -138,16 +138,21 @@ Each selector can be given a human-readable *NAME* to be displayed in the column
 header, by appending ``= NAME`` (or alternatively, ``AS name``, but that form is
 deprecated and should not be used anymore) to the selector.
 
-The ``user`` and ``label`` selectors accept a special syntactic sugar:
-``user:*`` and ``label:*`` will collect events for all contributors and for all
-labels in the repository, respectively. That is, ``--selector 'user:*'`` is
-equivalent for ``--selector user:user1 --selector user:user2 ...``, for all
-users *user1*, *user2*, ..., known to have contributed to the repository;
-likewise, ``--selector 'label:*'`` is equivalent to ``--selector label:label1
---selector label:label2 ...`` for all labels *label1*, *label2*, ..., ever used
-in the repository. Of note, only one wild-card selector may be used in any given
-expression: it is not possible to use both ``user:*`` and ``label:*`` inside the
-same selector option.
+The ``user`` selector accepts a special syntactic sugar: ``user:*TEAM`` will
+collect events for all users in team *TEAM* (or for all contributors if no team
+is specified, that is if the selector is simply ``user:*``). That is,
+``--selector 'user:*elite'`` is equivalent to ``--selector user:user1
+--selector user:user2 ...`` where *user1*, *user2*, etc. are members of the
+*elite* team.
+
+The ``team`` selector similarly accepts the syntactic sugar ``team:*``, which
+will collect events for all labels in the repository. That is, ``--selector
+'label:*'`` is equivalent to ``--selector label:label` --selector label:label2
+...`` for all labels *label1*, *label2*, etc. ever used in the repository.
+
+Of note, only one wild-card selector may be used in any given expression: it is
+not possible to use both ``user:*`` (with or without a team name) and
+``label:*`` inside the same selector option.
 
 Here is an example of a custom report request:
 
@@ -159,23 +164,49 @@ Here is an example of a custom report request:
        --selector 'label:bugfix = Bugs'
    From 2021-11-09 to 2022-05-08
    
-   | Event                | Total    | Others   | Othe (%) | Bugs     | Bugs (%) |
-   | -------------------- | -------- | -------- | -------- | -------- | -------- |
-   | Contributors         |       46 |       20 |    43.48 |       44 |    95.65 |
-   | Issues opened        |      184 |      116 |    63.04 |      136 |    73.91 |
-   | Issues closed        |      134 |      133 |    99.25 |      106 |    79.10 |
-   | Pull requests opened |      200 |      193 |    96.50 |      196 |    98.00 |
-   | Pull requests closed |      164 |      164 |   100.00 |      162 |    98.78 |
-   | Pull requests merged |      139 |      139 |   100.00 |      138 |    99.28 |
-   | Comments             |     1085 |      938 |    86.45 |        0 |     0.00 |
-   | Commits              |      485 |      475 |    97.94 |        0 |     0.00 |
-   | Releases             |        5 |        5 |   100.00 |        0 |     0.00 |
+   | Event | Total | Others | Others (%) | Bugs | Bugs (%) |
+   | -------- | -------- | -------- | -------- | -------- | -------- |
+   | Contributors | 46 | 20 | 43.48 | 44 | 95.65 |
+   | Issues opened | 184 | 116 | 63.04 | 136 | 73.91 |
+   | Issues closed | 134 | 133 | 99.25 | 106 | 79.10 |
+   | Pull requests opened | 200 | 193 | 96.50 | 196 | 98.00 |
+   | Pull requests closed | 164 | 164 | 100.00 | 162 | 98.78 |
+   | Pull requests merged | 139 | 139 | 100.00 | 138 | 99.28 |
+   | Comments | 1085 | 938 | 86.45 | 0 | 0.00 |
+   | Commits | 485 | 475 | 97.94 | 0 | 0.00 |
+   | Releases | 5 | 5 | 100.00 | 0 | 0.00 |
 
 It prints the numbers of all events in the repository, the number of events
 originating from users that are not members of the *elite* team, and the number
 of events labelled with the *bugfix* label.
 
 
+Special team names
+------------------
+
+The ``team`` selector will recognise a handful of special names, all starting with
+``__``:
+
+``team:__collaborators``
+    All users that are registered as collaborators on the repository.
+
+``team:__committers``
+    All users who ever committed to the repository.
+
+``team:__commenters``
+    All users who ever opened a ticket or a PR or commented on a ticket or a PR.
+
+``team:__contributors``
+    All users who ever contributed anything (commit, issue, PR, comment) to the
+    repository.
+
+These names are also recognised by the ``user:*TEAM`` syntactic sugar. For
+example, ``--selector 'user:*__committers'`` will be equivalent to ``--selector
+user:user1 --selector user:user2 ...`` where *user1*, *user2*, etc. are users
+who contributed commits to the repository. The special ``user:*`` sugar is
+strictly equivalent to ``user:*__contributors``. 
+
+
 Report formats
 --------------
 
@@ -205,17 +236,17 @@ Here is an example of the effect of the ``= NAME`` syntax:
        --selector 'label:bugfix'
    From 2021-11-09 to 2022-05-08
    
-   | Event                | Others   | label:bu |
-   | -------------------- | -------- | -------- |
-   | Contributors         |       20 |       44 |
-   | Issues opened        |      116 |      136 |
-   | Issues closed        |      133 |      106 |
-   | Pull requests opened |      193 |      196 |
-   | Pull requests closed |      164 |      162 |
-   | Pull requests merged |      139 |      138 |
-   | Comments             |      938 |        0 |
-   | Commits              |      475 |        0 |
-   | Releases             |        5 |        0 |
+   | Event | Others | label:bugfix |
+   | -------- | -------- | -------- |
+   | Contributors | 20 | 44 |
+   | Issues opened | 116 | 136 |
+   | Issues closed | 133 | 106 |
+   | Pull requests opened | 193 | 196 |
+   | Pull requests closed | 164 | 162 |
+   | Pull requests merged | 139 | 138 |
+   | Comments | 938 | 0 |
+   | Commits | 475 | 0 |
+   | Releases | 5 | 0 |
 
 As a convenience, if the *first* selector is the ``all`` selector, then for each
 subsequent selector, an extra column is appended to give the proportion of
@@ -228,17 +259,17 @@ events corresponding to the selector relatively to all events:
        --selector '!team:elite = Others'
    From 2021-11-09 to 2022-05-08
    
-   | Event                | Total    | Others   | Othe (%) |
-   | -------------------- | -------- | -------- | -------- |
-   | Contributors         |       46 |       20 |    43.48 |
-   | Issues opened        |      184 |      116 |    63.04 |
-   | Issues closed        |      134 |      133 |    99.25 |
-   | Pull requests opened |      200 |      193 |    96.50 |
-   | Pull requests closed |      164 |      164 |   100.00 |
-   | Pull requests merged |      139 |      139 |   100.00 |
-   | Comments             |     1085 |      938 |    86.45 |
-   | Commits              |      485 |      475 |    97.94 |
-   | Releases             |        5 |        5 |   100.00 | 
+   | Event | Total | Others | Others (%) |
+   | -------- | -------- | -------- | -------- |
+   | Contributors | 46 | 20 | 43.48 |
+   | Issues opened | 184 | 116 | 63.04 |
+   | Issues closed | 134 | 133 | 99.25 |
+   | Pull requests opened | 200 | 193 | 96.50 |
+   | Pull requests closed | 164 | 164 | 100.00 |
+   | Pull requests merged | 139 | 139 | 100.00 |
+   | Comments | 1085 | 938 | 86.45 |
+   | Commits | 485 | 475 | 97.94 |
+   | Releases | 5 | 5 | 100.00 | 
 
 
 JSON format