Repository navigation
Description
Held RFC. This is a design proposal for discussion. It carries hold so no hive agent picks it up until maintainers settle Decisions for maintainers.
| Field | Value |
|---|---|
| Status | Proposal, not accepted |
| Target | v5 |
| Scope | src/pkg/rfcnotify (detector, sweeper, Format), src/pkg/discord/bot.go (SendMessageTo), src/cmd/hive/rfcnotify_wire.go, the issues / pull_request webhook path in src/pkg/dashboard/api_github_webhook.go, notifications.discord.* config, src/docs/notifications.md |
| Out of scope | Two-way sync (Discord replies β GitHub comments), slash commands for voting, any other Discord channel |
| Builds on | #14616 / #14617 (RFC lifecycle notices, merged on v5 2026-10-27) |
| Channel | #architecture-rfcs, https://discord.com/channels/1539670512744136715/1540404487099777136 |
Summary
RFCs already reach Discord automatically. #14617 shipped pkg/rfcnotify: set notifications.discord.rfc_channel_id (the docs example is this channel, 1540404487099777136) and the hive polls every 3 min. It posts one plain line when an RFC issue is opened, when it closes, and when its hold comes off.
This RFC makes that feed something people read and discuss rather than scroll past:
- a summary card instead of a bare link;
- one Discord thread per RFC, with later lifecycle events posted into it;
- the edits that matter (decisions resolved, target changed);
- RFC documents that arrive as PRs;
- no duplicate announcements;
- near-instant posting through webhooks.
Gaps in what ships today
| Gap | Effect |
|---|---|
A plain one-liner: RFC opened: #N <title> - <url> (by @author) |
No summary, target line, status or open-decision count, so readers have no reason to click |
| No discussion home | Replies scatter across the channel and nothing ties them back to the RFC or the GitHub issue |
| Only opened, closed and hold-removed | No notice when the "Decisions for maintainers" get resolved, the target line changes, or the RFC reaches stage/045-needs-decision |
| Issues only | RFC documents proposed as π proposal: PRs or docs/rfc-*.md files (for example, the constellation and capacity RFCs) are never announced |
| No dedup | The same RFC filed twice, as happened with #15855β#15857 / #15860β#15862, is announced twice, and so is its duplicate close |
| One announcer per hive | Detector state lives in each hive's /data/rfc-notify.json. If two hives manage the same repo and both set the key, both post |
| 3-minute poll | Adequate, but the hive already receives issues webhooks |
Design
A. Summary card
Each post becomes a Discord embed. When the body can't be parsed, the post falls back to today's line.
- Title.
#N <title>, linked to the issue. Author, with avatar. - Fields parsed from the RFC table, when the body follows the repo's RFC shape:
Target(v5/v6),Status,- the first paragraph of the summary (β€ 300 chars, run through
logscrub), - the number of open items under Decisions for maintainers,
- related RFC links.
- Colour by state. Held (grey), needs decision (amber), ready to implement (green), closed completed (blue), closed not planned (dark).
B. One thread per RFC
- After posting the "opened" card, the bot starts a thread on that message, named
#N <short title>. Later events for the RFC post into the thread. Closed and ready-to-implement also get a one-line echo in the channel. - Optional backlink. With
rfc_backlink_comment: true, the bot leaves one comment on the GitHub issue: "Discussion thread: ". - Recording. The detector records the message and thread IDs per issue in
/data/rfc-notify.json, so restarts keep posting into the same thread.
C. More lifecycle events
- Decisions changed. The count of open decisions changed, or a decision was struck through or checked. Debounced to 30 min.
- Target or status changed.
- Needs a decision.
stage/045-needs-decisionorneeds-humanwas added. - Retitled. The bot edits the card and renames the thread instead of posting.
- Comment digest. Off by default: one "N new comments" line per thread per day.
D. RFC documents via PR
A PR is treated as an RFC when it is titled π proposal: or π RFC, or when it adds or changes docs/rfc-*.md. It gets the same card, with the document's title and the PR link. Merging the PR posts "RFC doc accepted" into the thread of the linked RFC issue, if there is one.
E. Dedup and a single announcer
- Same RFC, same author. If an RFC has the same normalised title and author as one opened in the last hour, the bot posts nothing new. It adds "duplicate filed as #M" to the first RFC's thread. When the duplicate is closed, the bot says nothing.
- Idempotent across hives. Before posting an "opened" card, the bot reads the channel's last 100 messages and skips the post if one already links that issue URL. A second hive pointed at the same channel then adopts the existing thread instead of posting again. This needs no hub coordination; Decision 3 covers the alternative of a hub-owned announcer.
F. Faster delivery
issues and pull_request webhook deliveries for managed repos trigger an immediate sweep of that one item. The 3-minute poll stays as the backstop and still owns the watermark.
G. Safety
- Posts set
allowed_mentions: {"parse": []}, so titles and summaries written by anyone who can open an issue can never ping@everyone, roles or users. - Embed text is truncated and passed through
logscrub. - Private-repo RFCs are announced only if
rfc_include_private: true, because the channel is public.
Config
notifications:
discord:
bot_token: ${DISCORD_BOT_TOKEN}
rfc_channel_id: "1540404487099777136" # existing
rfc_format: card # card | line (today's behaviour)
rfc_threads: true
rfc_backlink_comment: false
rfc_include_private: false
rfc_comment_digest: falseEvery new key defaults to today's behaviour, except rfc_format: card and rfc_threads: true (Decision 1).
Rollout
- Card,
allowed_mentions, dedup and the cross-hive idempotency check. - Threads and backlinks.
- New lifecycle events, plus webhook-triggered sweeps.
- Proposal PRs and RFC docs.
Acceptance
- Opening a well-formed RFC posts one card with its target, summary and decision count, and starts a thread. Closing it posts into the thread and echoes one line to the channel.
- Two identical RFCs from one author within an hour produce one card and a thread note. Closing the duplicate posts nothing.
- Two hives configured with the same channel produce one card per RFC.
- A title containing
@everyoneor<@&role>pings nobody. Covered by a test on the request payload. - A restart neither re-posts nor loses the thread mapping.
- A
docs/rfc-*.mdPR is announced. - Tests in
pkg/rfcnotifycover parsing, dedup and event detection.notifications.mdandoperator-reference.mdupdated.changelog.dfragment included.
Alternatives
- GitHub's Discord webhook integration. It posts every issue event, not just RFCs, with no threads, no parsing and no dedup.
- Discord Forum channel, one post per RFC. A neat fit, but it would mean converting
#architecture-rfcsto a Forum channel and moving its history (Decision 2). - A hub-owned announcer. One source of truth, but it ties RFC notices to a hub that self-hosted hives may not use.
Decisions for maintainers
- Defaults. Make
cardand threads the default on upgrade (proposed), or keep today's one-liner and opt in? - Text channel or Forum channel. Keep
#architecture-rfcsas a text channel with threads (proposed), or move to a Forum channel? - Single announcer. The channel-history idempotency check (proposed), or designate one hive or the hub as the announcer?
- Backlink comment. Should the bot comment on GitHub issues it did not open?
- Comment digest. Daily per-thread digest: in scope, or later?
Activity
hivecommons-hive commentedon Oct 31, 2026
Parking on
stage/045-needs-decision: this RFC is marked Proposal, not accepted and its body says it should carryholduntil the Decisions for maintainers are settled, but the label was never applied, so it landed in the actionable queue. The hive will not change what it posts to a public Discord channel, or start commenting on GitHub issues it did not open, without an accepted design.Risk: public-facing / irreversible actions (public Discord posts, threads, and optional backlink comments on others' issues).
Maintainer question β pick one and the hive proceeds:
#architecture-rfcsa text channel, channel-history idempotency for single-announcer, no backlink comments on issues the bot did not open, comment digest deferred.notifications.discord.rfc_format: card/rfc_threads: trueoff by default), otherwise as in A.Reply
/hive decision A|B|C(or/hive approvefor A).β hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88
hivecommons-hive commentedon Oct 31, 2026
What to reply
/hive approve: go with the recommendation/hive decision <your instructions>: go ahead, following your instructions/hive help: show these againIf what this issue waited on has been done (a merged fix, or an action taken outside this repository), a maintainer can reply
/fixedto close it as completed; Hive clears its park labels.Only a maintainer with write access can un-park; everything else is ignored. Full command reference: https://github.com/hivecommons/hive/blob/v5/src/docs/maintainer-commands.md.
clubanderson commentedon Oct 31, 2026
/hive decision Proceed with richer RFC publishing as an opt-in upgrade: preserve the existing one-line behavior unless cards/threads are explicitly enabled. Keep the existing text channel and create one thread per RFC, not a Forum migration. Use one explicitly designated announcer per destination with durable idempotency and reconciliation; do not rely on channel-history scanning as an atomic distributed claim, and do not let every hive race to publish. Optional history lookup may reconcile crash/retry uncertainty but must not trigger unbounded backfill or duplicate announcements. Backlinks on GitHub are opt-in and posted at most once only after the actual Discord thread is confirmed; no automatic comments on others issues by default. Defer daily comment digests and two-way sync. Preserve authorization: do not publish private repository titles, bodies, links or discussions into a channel without an explicit authorized destination policy. Bound retries, respect rate limits and surface failures. Source implementation is authorized; no live Discord configuration, channel changes or historical announcement burst is authorized.
hivecommons-hive commentedon Oct 31, 2026
Un-parked by @clubanderson. Decision: Proceed with richer RFC publishing as an opt-in upgrade: preserve the existing one-line behavior unless cards/threads are explicitly enabled. Keep the existing text channel and create one thread per RFC, not a Forum migration. Use one explicitly designated announcer per destination with durable idempotency and reconciliation; do not rely on channel-history scanning as an atomic distributed claim, and do not let every hive race to publish. Optional history lookup may reconcile crash/retry uncertainty but must not trigger unbounded backfill or duplicate announcements. Backlinks on GitHub are opt-in and posted at most once only after the actual Discord thread is confirmed; no automatic comments on others issues by default. Defer daily comment digests and two-way sync. Preserve authorization: do not publish private repository titles, bodies, links or discussions into a channel without an explicit authorized destination policy. Bound retries, respect rate limits and surface failures. Source implementation is authorized; no live Discord configuration, channel changes or historical announcement burst is authorized.
stage/045-needs-decisionis cleared when present andapproved-directionis applied; anyholdlabel is left exactly as it was.13 remaining items
hivecommons-hive commentedon Oct 31, 2026
Verified once after #15947 merged: the RFC is not fully resolved, so it stays open as
hive/verified-open.Landed on v5: #15926 (opt-in rich config, announcer + private-repo gates; via #15947) and the "RFC documents that arrive as PRs" part (via #15959). Still open, each tracked by its own child so this tracker is not re-triaged every cycle:
Nothing is left to implement directly on this issue; it closes when the last child does.
π Hive Agent:
scanner| Instance:hosted-available-oke-11-placeholder-r05x| SHA:unknownβ hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88
hivecommons-hive commentedon Oct 31, 2026
PR #16018 covers this issue: #16018
The PR body says this is partial/non-closing work (
Refs/Part ofor leave-open wording), so Hive will not add a closing keyword. GitHub will not show its issue-list PR icon without a closing keyword; the stage comment is the link.hivecommons-hive commentedon Oct 31, 2026
All children delivered: #15926 β PR #15947, #15927 β PR #15999, #15939 β PR #15994, #15940 β PR #16018.
Every tracked child of this issue is closed, so the hive is closing it as completed. Reopen it if something it asked for is still missing.
github-actions commentedon Oct 31, 2026
@hanthor this issue was closed by @hivecommons-hive[bot] as completed.
If this was closed by a merged PR, the fix only takes effect once it ships in a tagged release and your deployment updates to it β check your running version against the fix before concluding the fix failed.
If you are still seeing the problem, comment
/reopenand it will be reopened for you β you do not need write access. Please add what you are still observing (running version, logs, steps) so it is not closed the same way again.