Skip to content

πŸ“ RFC: Richer RFC publishing to Discord #architecture-rfcs β€” summary cards, one thread per RFC, dedupΒ #15869

Closed
4 of 4 issues completed

Description

@hanthor

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-decision or needs-human was 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: false

Every new key defaults to today's behaviour, except rfc_format: card and rfc_threads: true (Decision 1).

Rollout

  1. Card, allowed_mentions, dedup and the cross-hive idempotency check.
  2. Threads and backlinks.
  3. New lifecycle events, plus webhook-triggered sweeps.
  4. 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 @everyone or <@&role> pings nobody. Covered by a test on the request payload.
  • A restart neither re-posts nor loses the thread mapping.
  • A docs/rfc-*.md PR is announced.
  • Tests in pkg/rfcnotify cover parsing, dedup and event detection. notifications.md and operator-reference.md updated. changelog.d fragment 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-rfcs to 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

  1. Defaults. Make card and threads the default on upgrade (proposed), or keep today's one-liner and opt in?
  2. Text channel or Forum channel. Keep #architecture-rfcs as a text channel with threads (proposed), or move to a Forum channel?
  3. Single announcer. The channel-history idempotency check (proposed), or designate one hive or the hub as the announcer?
  4. Backlink comment. Should the bot comment on GitHub issues it did not open?
  5. Comment digest. Daily per-thread digest: in scope, or later?

Activity

  1. added
    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.
    kind/designCreated by Hive for agent-filed issue provenance
    proposalRFC / design proposal for discussion
    on Oct 30, 2026
  2. hivecommons-hive commented on Oct 31, 2026

    @hivecommons-hive
    Contributor

    Parking on stage/045-needs-decision: this RFC is marked Proposal, not accepted and its body says it should carry hold until 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:

    • A. Accept with the proposed defaults: embed cards + one thread per RFC on by default, keep #architecture-rfcs a text channel, channel-history idempotency for single-announcer, no backlink comments on issues the bot did not open, comment digest deferred.
    • B. Accept as opt-in only (notifications.discord.rfc_format: card / rfc_threads: true off by default), otherwise as in A.
    • C. Keep held β€” not yet; or decline.

    Reply /hive decision A|B|C (or /hive approve for A).

    β€” hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88

  3. added
    stage/045-needs-decisionIssue parked on a person: needs-human or a maintainer decision is owed before the hive picks it up
    and removed
    stage/010-actionableTriaged; eligible for the hive to pick up
    on Oct 31, 2026
  4. hivecommons-hive commented on Oct 31, 2026

    @hivecommons-hive
    Contributor

    What to reply

    • /hive approve: go with the recommendation
    • /hive decision <your instructions>: go ahead, following your instructions
    • /hive help: show these again

    If what this issue waited on has been done (a merged fix, or an action taken outside this repository), a maintainer can reply /fixed to 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.

  5. clubanderson commented on Oct 31, 2026

    @clubanderson
    Member

    /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.

  6. added
    stage/010-actionableTriaged; eligible for the hive to pick up
    and removed
    stage/045-needs-decisionIssue parked on a person: needs-human or a maintainer decision is owed before the hive picks it up
    on Oct 31, 2026
  7. hivecommons-hive commented on Oct 31, 2026

    @hivecommons-hive
    Contributor

    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-decision is cleared when present and approved-direction is applied; any hold label is left exactly as it was.

  8. 13 remaining items

  9. added
    stage/010-actionableTriaged; eligible for the hive to pick up
    hive/verified-openHive verified that a likely/already-done claim did not finish this issue; keep open for more work
    and removed
    stage/010-actionableTriaged; eligible for the hive to pick up
    on Oct 31, 2026
  10. hivecommons-hive commented on Oct 31, 2026

    @hivecommons-hive
    Contributor

    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

  11. hivecommons-hive commented on Oct 31, 2026

    @hivecommons-hive
    Contributor

    PR #16018 covers this issue: #16018

    The PR body says this is partial/non-closing work (Refs/Part of or 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.

  12. hivecommons-hive commented on Oct 31, 2026

    @hivecommons-hive
    Contributor

    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.

  13. github-actions commented on Oct 31, 2026

    @github-actions
    Contributor

    @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 /reopen and 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    approved-directionhelp wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.hive/partially-addressedA merged PR addressed only part of this issue; remainder still actionablehive/verified-openHive verified that a likely/already-done claim did not finish this issue; keep open for more workkind/designCreated by Hive for agent-filed issue provenanceproposalRFC / design proposal for discussion

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions