doc(plugins/contributors): update

2022-01-15 22:36:41 -05:00
parent 34203e9a07
commit 4fc8ab8fcf
2 changed files with 86 additions and 68 deletions
--- a/source/plugins/contributors/README.md
+++ b/source/plugins/contributors/README.md
@@ -1,40 +1,29 @@
-### 🏅 Repository contributors
-
-The *contributors* plugin lets you display repositories contributors from a commit range, that can be specified through either sha, tags, branch, etc.
-
-It's especially useful to acknowledge contributors on release notes.
-
+<!--header-->
 <table>
-  <td align="center">
-    <details open><summary>By contribution types</summary>
-      <img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.contributors.categories.svg">
-    </details>
-    <details><summary>By number of contributions</summary>
-      <img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.contributors.contributions.svg">
-    </details>
+  <tr><th colspan="2"><h3>🏅 Repository contributors</h3></th></tr>
+  <tr><td colspan="2" align="center"><p>This plugin display repositories contributors from a commit range along with additional stats.</p>
+</td></tr>
+  <tr>
+    <th rowspan="3">Supported features<br><sub><a href="metadata.yml">→ Full specification</a></sub></th>
+    <td><a href="/source/templates/repository"><code>📘 Repository template</code></a></td>
+  </tr>
+  <tr>
+    <td><code>📓 Repositories</code></td>
+  </tr>
+  <tr>
+    <td><code>🔑 (scopeless)</code> <code>read:org (optional)</code> <code>read:user (optional)</code> <code>repo (optional)</code></td>
+  </tr>
+  <tr>
+    <td colspan="2" align="center">
+      <details open><summary>By contribution types</summary><img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.contributors.categories.svg" alt=""></img></details>
+      <details><summary>By number of contributions</summary><img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.contributors.contributions.svg" alt=""></img></details>
      <img width="900" height="1" alt="">
    </td>
+  </tr>
 </table>
+<!--/header-->

-**Displaying contributors per categories**
-
-> 🔣 On web instances, sorting contributors per categories is an extra feature and must be enabled globally in `settings.json`
-
-To configure contributions categories, pass a JSON object to `plugin_contributors_categories` (use `|` multiline operator for better readability) with categories names as keys and an array of file glob as values:
-
-```yaml
-plugin_contributors_categories: |
-  {
-    "📚 Documentation": ["README.md", "docs/**"],
-    "💻 Code": ["source/**", "src/**"],
-    "#️⃣ Others": ["*"]
-  }
-```
-
-Each time a file modified by a contributor match a fileglob, they will be added in said category.
-Matching is performed in keys order.
-
-#### ➡️ Available options
+## ➡️ Available options

 <!--options-->
 <table>
@@ -43,7 +32,7 @@ Matching is performed in keys order.
  </tr>
  <tr>
    <td nowrap="nowrap"><code>plugin_contributors</code></td>
-    <td rowspan="2"><p>Display repository contributors</p>
+    <td rowspan="2"><p>Enable contributors plugin</p>
 <img width="900" height="1" alt=""></td>
  </tr>
  <tr>
@@ -53,7 +42,7 @@ Matching is performed in keys order.
  </tr>
  <tr>
    <td nowrap="nowrap"><code>plugin_contributors_base</code></td>
-    <td rowspan="2"><p>Base reference</p>
+    <td rowspan="2"><p>Base reference (commit, tag, branch, etc.)</p>
 <img width="900" height="1" alt=""></td>
  </tr>
  <tr>
@@ -62,7 +51,7 @@ Matching is performed in keys order.
  </tr>
  <tr>
    <td nowrap="nowrap"><code>plugin_contributors_head</code></td>
-    <td rowspan="2"><p>Head reference</p>
+    <td rowspan="2"><p>Head reference (commit, tag, branch, etc.)</p>
 <img width="900" height="1" alt=""></td>
  </tr>
  <tr>
@@ -72,19 +61,19 @@ Matching is performed in keys order.
  </tr>
  <tr>
    <td nowrap="nowrap"><code>plugin_contributors_ignored</code></td>
-    <td rowspan="2"><p>Contributors to ignore</p>
+    <td rowspan="2"><p>Ignored users</p>
+<p>Useful to ignore bots activity</p>
 <img width="900" height="1" alt=""></td>
  </tr>
  <tr>
    <td nowrap="nowrap">⏩ Inherits <code>users_ignored</code><br>
 <b>type:</b> <code>array</code>
 <i>(comma-separated)</i>
-<br>
-<b>default:</b> github-actions[bot], dependabot[bot], dependabot-preview[bot]<br></td>
+<br></td>
  </tr>
  <tr>
    <td nowrap="nowrap"><code>plugin_contributors_contributions</code></td>
-    <td rowspan="2"><p>Display contributions</p>
+    <td rowspan="2"><p>Toggle number of contributions display</p>
 <img width="900" height="1" alt=""></td>
  </tr>
  <tr>
@@ -94,7 +83,11 @@ Matching is performed in keys order.
  </tr>
  <tr>
    <td nowrap="nowrap"><code>plugin_contributors_sections</code></td>
-    <td rowspan="2"><p>Sections to display</p>
+    <td rowspan="2"><p>Displayed sections</p>
+<ul>
+<li><code>contributors</code>: all contributors</li>
+<li><code>categories</code>: contributors sorted by contributions categories</li>
+</ul>
 <img width="900" height="1" alt=""></td>
  </tr>
  <tr>
@@ -106,7 +99,9 @@ Matching is performed in keys order.
  </tr>
  <tr>
    <td nowrap="nowrap"><code>plugin_contributors_categories</code></td>
-    <td rowspan="2"><p>Contributions categories</p>
+    <td rowspan="2"><p>Configure contribution categories</p>
+<p>This option required <code>plugin_contributors_sections</code> to have <code>categories</code> in it to be effective
+Pass a JSON object mapping category with fileglobs</p>
 <img width="900" height="1" alt=""></td>
  </tr>
  <tr>
@@ -123,9 +118,30 @@ Matching is performed in keys order.
 </table>
 <!--/options-->

-*[→ Full specification](metadata.yml)*
+## 🗂️ Setting up contribution categories

-#### ℹ️ Examples workflows
+Pass a JSON object to `plugin_contributors_categories` with categories names as keys and arrays of fileglobs as values to configure contributions categories.
+
+Each modified file by a contributor matching a fileglob will add them in said category.
+
+> 💡 File matching respect keys order
+
+> 💡 Use `|` YAML multiline operator for better readability
+
+*Example: *
+```yaml
+- uses: lowlighter/metrics@latest
+  with:
+    plugin_contributors: yes
+    plugin_contributors_categories: |
+      {
+        "📚 Documentation": ["README.md", "docs/**"],
+        "💻 Code": ["source/**", "src/**"],
+        "#️⃣ Others": ["*"]
+      }
+```
+
+## ℹ️ Examples workflows

 <!--examples-->
 ```yaml
--- a/source/plugins/contributors/metadata.yml
+++ b/source/plugins/contributors/metadata.yml
@@ -1,5 +1,9 @@
 name: "🏅 Repository contributors"
 category: github
+description: This plugin display repositories contributors from a commit range along with additional stats.
+examples:
+  +by contribution types: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.contributors.categories.svg
+  by number of contributions: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.contributors.contributions.svg
 index: 6
 supports:
  - repository
@@ -7,58 +11,56 @@ scopes:
  - public_access
 inputs:

-  # Enable or disable plugin
  plugin_contributors:
-    description: Display repository contributors
+    description: Enable contributors plugin
    type: boolean
    default: no

-  # Base reference (commit, tag, branch, etc.)
  plugin_contributors_base:
-    description: Base reference
+    description: Base reference (commit, tag, branch, etc.)
    type: string
    default: ""
    example: commit, tag or branch

-  # Head reference (commit, tag, branch, etc.)
  plugin_contributors_head:
-    description: Head reference
+    description: Head reference (commit, tag, branch, etc.)
    type: string
    default: master

-  # Ignored contributors (useful to ignore bots users)
  plugin_contributors_ignored:
-    description: Contributors to ignore
+    description: |
+      Ignored users
+
+      Useful to ignore bots activity
    type: array
    format: comma-separated
-    default: github-actions[bot], dependabot[bot], dependabot-preview[bot]
+    default: ""
    inherits: users_ignored

-  # Display total contributions for each contributor
  plugin_contributors_contributions:
-    description: Display contributions
+    description: Toggle number of contributions display
    type: boolean
    default: no

-  # Sections to display
  plugin_contributors_sections:
-    description: Sections to display
+    description: |
+      Displayed sections
+      - `contributors`: all contributors
+      - `categories`: contributors sorted by contributions categories
    type: array
    format: comma-separated
    default: contributors
    example: contributors
    values:
-      - contributors # Display all contributors
-      - categories   # Display contributors per contributions categories
+      - contributors
+      - categories

-  # Contributions categories
-  # This requires "plugin_contributors_sections" to have "categories" in it to be effective
-  #
-  # Pass a JSON object which contains a mapping of category with fileglobs.
-  # Contributors will be sorted into each category to reflect their contributions.
-  # Note that order a file will only match the first category matching
  plugin_contributors_categories:
-    description: Contributions categories
+    description: |
+      Configure contribution categories
+
+      This option required `plugin_contributors_sections` to have `categories` in it to be effective
+      Pass a JSON object mapping category with fileglobs
    type: json
    default: |
      {