Add Drone Discord changelog pipeline and test notification

2026-10-17 17:07:01 +02:00
parent 96f471ef4a
commit 8f2e1f210d
7 changed files with 405 additions and 4 deletions
@@ -0,0 +1,70 @@
+# Discord changelogs through Drone
+
+`.drone.yml` runs a Docker pipeline for pushes to `main`. It tests the notifier,
+then reads `CHANGELOG.md` from the pushed commit. Discord receives only the newest
+entry's heading and body, with mentions disabled and no build, Git or hosting
+status added.
+
+## One-time setup
+
+1. Connect Drone to Gitea and activate this repository in Drone. A Docker runner
+   must be available. Keep the configuration filename at `.drone.yml`.
+2. In this repository's **Drone settings → Secrets**, add `discord_webhook_url`.
+   Use the existing webhook URL stored locally in `.local/discord-webhook.url`.
+   Do not put the URL in Git or enable the secret for pull requests.
+3. Push these files to `main`, then verify the `notify-discord` step and its
+   corresponding Discord message. Creating the YAML alone does not activate Drone
+   or install its Gitea webhook.
+4. Once Drone delivery is enabled, stop the manual post-push notifier. Both
+   delivery paths running for the same push would produce duplicate messages.
+
+Drone's repository activation manages the Gitea event webhook. This notification
+pipeline does not compile, publish or update the mission.
+
+## Updating the changelog
+
+Prepend a new level-two heading and player-facing bullets for each update:
+
+```markdown
+## 2026-10-18 — Checkpoint improvements
+
+- Improved checkpoint cover and approach barriers.
+- Added a small rest tent and inspection table.
+```
+
+Keep headings unique, newest first, with no empty placeholder section at the top.
+Use a distinct title for multiple updates on the same date. Entries are plain
+Markdown prose/lists; level-three headings are supported. Do not use level-two
+headings inside code examples within an entry. Keep the formatted newest entry
+within Discord's 2000-character limit; oversized entries fail without truncation.
+The dated files in `publishing/` remain separate Workshop release notes.
+
+The notifier compares `DRONE_COMMIT_BEFORE` with `DRONE_COMMIT_SHA`, covering the
+whole push, even when a documentation commit follows the changelog commit.
+Unchanged newest entries, historical edits and removing an entry to expose an
+older one do not post. Editing the current newest entry posts its revised text.
+If a push adds several entries, only the newest is posted. Combine their notes
+in one top entry when all changes should appear in the announcement.
+
+The first push introducing `CHANGELOG.md` posts its newest entry. It does not
+backfill older release notes. Missing Git history fails instead of guessing a
+previous revision; an exact-SHA fetch is attempted for a missing before commit.
+
+## Verification and delivery failures
+
+Run `python3 -m unittest discover -s tests -p test_discord_changelog_ci.py` locally.
+The tests use temporary Git repositories and mocked HTTP; they send no messages.
+`python3 tools/discord_changelog_ci.py --dry-run` inside a Drone checkout with its
+normal commit environment prints the selected message without using the secret.
+
+Delivery uses `wait=true` and requires Discord's message confirmation. Errors
+fail the step without printing the webhook URL. There are no automatic HTTP
+retries. Inspect Discord before manually rebuilding a delivery step: a timed-out
+request may already have arrived. Drone workspaces are ephemeral, so rerunning
+the same push is not deduplicated across builds; exactly-once delivery is not
+claimed.
+
+References: [Drone push triggers](https://docs.drone.io/pipeline/docker/syntax/trigger/),
+[repository secrets](https://docs.drone.io/secret/repository/),
+[push before commit](https://docs.drone.io/pipeline/environment/reference/drone-commit-before/),
+[Discord webhooks](https://docs.discord.com/developers/resources/webhook#execute-webhook).