From 4fc8ab8fcf9e0c5563317c09b6773b9d41f2075a Mon Sep 17 00:00:00 2001 From: lowlighter <22963968+lowlighter@users.noreply.github.com> Date: Sat, 15 Jan 2022 22:36:41 -0500 Subject: [PATCH] doc(plugins/contributors): update --- source/plugins/contributors/README.md | 108 +++++++++++++---------- source/plugins/contributors/metadata.yml | 46 +++++----- 2 files changed, 86 insertions(+), 68 deletions(-) diff --git a/source/plugins/contributors/README.md b/source/plugins/contributors/README.md index 1f7a995f..61145f1d 100644 --- 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. - + - + + + + + + + + + + + + + + +
-
By contribution types - -
-
By number of contributions - -
- -

🏅 Repository contributors

This plugin display repositories contributors from a commit range along with additional stats.

+
Supported features
→ Full specification		📘 Repository template
📓 Repositories
🔑 (scopeless) read:org (optional) read:user (optional) repo (optional)
+
By contribution types
+
By number of contributions
+ +
+ -**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 @@ -43,7 +32,7 @@ Matching is performed in keys order. - @@ -53,7 +42,7 @@ Matching is performed in keys order. - @@ -62,7 +51,7 @@ Matching is performed in keys order. - @@ -72,19 +61,19 @@ Matching is performed in keys order. - +
- @@ -94,7 +83,11 @@ Matching is performed in keys order. - @@ -106,7 +99,9 @@ Matching is performed in keys order. - @@ -123,9 +118,30 @@ Matching is performed in keys order.
plugin_contributors

Display repository contributors

+

Enable contributors plugin
plugin_contributors_base

Base reference

+

Base reference (commit, tag, branch, etc.)
plugin_contributors_head

Head reference

+

Head reference (commit, tag, branch, etc.)
plugin_contributors_ignored

Contributors to ignore

+

Ignored users

+

Useful to ignore bots activity
⏊ Inherits users_ignored
type: array (comma-separated) -
-default: github-actions[bot], dependabot[bot], dependabot-preview[bot]
plugin_contributors_contributions

Display contributions

+

Toggle number of contributions display
plugin_contributors_sections

Sections to display

+

Displayed sections

+
    +
  • contributors: all contributors
    • +
  • categories: contributors sorted by contributions categories
    • +
plugin_contributors_categories

Contributions categories

+

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
-*[→ 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 ```yaml @@ -160,4 +176,4 @@ with: } ``` - \ No newline at end of file + diff --git a/source/plugins/contributors/metadata.yml b/source/plugins/contributors/metadata.yml index 24caa471..5e0fc9b9 100644 --- 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: | {