Merge pull request #2559 from alexbelgium/codex/improve-documentation-for-user-addons

Document community-submitted add-ons and auto-mention submitters on issues

.github/addon_submitters.json

@@ -0,0 +1,4 @@
+{
+  "whatsapper": "baldarn",
+  "spotweb": "woutercoppens"
+}

.github/workflows/on_issues_ping_submitter.yml

@@ -0,0 +1,52 @@
+---
+name: Issue add-on submitter ping
+
+on:
+  issues:
+    types: [opened, edited, reopened]
+
+permissions:
+  issues: write
+
+jobs:
+  ping_submitter:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Ping mapped submitter when add-on is mentioned
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          ISSUE_TITLE: ${{ github.event.issue.title }}
+          ISSUE_BODY: ${{ github.event.issue.body }}
+          ISSUE_NUMBER: ${{ github.event.issue.number }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+
+          TEXT="${ISSUE_TITLE} ${ISSUE_BODY}"
+          TEXT_LOWER="$(printf '%s' "$TEXT" | tr '[:upper:]' '[:lower:]')"
+
+          while IFS= read -r addon; do
+            [ -z "$addon" ] && continue
+
+            if [[ "$TEXT_LOWER" == *"$addon"* ]]; then
+              user="$(jq -r --arg addon "$addon" '.[$addon]' .github/addon_submitters.json)"
+              [ -z "$user" ] && continue
+
+              marker="<!-- addon-submitter-ping:${addon} -->"
+              comments_url="https://api.github.com/repos/${REPO}/issues/${ISSUE_NUMBER}/comments"
+
+              existing="$(curl -sS -H "Authorization: Bearer ${GITHUB_TOKEN}" -H 'Accept: application/vnd.github+json' "$comments_url" | jq -r --arg marker "$marker" '[ .[] | select(.body | contains($marker)) ] | length')"
+
+              if [ "$existing" -eq 0 ]; then
+                body=$(jq -cn --arg marker "$marker" --arg addon "$addon" --arg user "$user" '{body: ($marker + "\nHeads up @" + $user + ": this issue appears to mention `" + $addon + "`.")}')
+                curl -sS -X POST \
+                  -H "Authorization: Bearer ${GITHUB_TOKEN}" \
+                  -H 'Accept: application/vnd.github+json' \
+                  "$comments_url" \
+                  -d "$body" > /dev/null
+              fi
+            fi
+          done < <(jq -r 'keys[]' .github/addon_submitters.json)

COMMUNITY_SUBMITTED_ADDONS.md

@@ -0,0 +1,17 @@
+# Community-submitted add-ons
+
+This repository tracks add-ons that were initially proposed/submitted by community members.
+
+When an issue mentions one of these add-ons (in the title or body), a GitHub Action automatically posts a mention to notify the corresponding person.
+
+## Current list
+
+| Add-on folder | Initial submitter |
+| --- | --- |
+| `whatsapper` | [@baldarn](https://github.com/baldarn) |
+| `spotweb` | [@woutercoppens](https://github.com/woutercoppens) |
+
+## How to update this list
+
+1. Add or update an entry in `.github/addon_submitters.json` with the add-on folder name as key and the GitHub username as value.
+2. Keep this markdown table in sync so it remains visible to users.

README.md

@@ -32,6 +32,8 @@ _Thanks to all contributors !_
 
 [![contributors](https://contrib.rocks/image?repo=alexbelgium/hassio-addons)](https://github.com/alexbelgium/hassio-addons/graphs/contributors)
 
+Community-submitted add-ons (and who to ping when related issues are opened): [COMMUNITY_SUBMITTED_ADDONS.md](COMMUNITY_SUBMITTED_ADDONS.md)
+
 Stargazers locations :
 
 ![map](https://raw.githubusercontent.com/alexbelgium/hassio-addons/refs/heads/master/.github/stargazer_map.png)