[llvm] [llvm][Docs] add discord bot calendar capability notes (PR #122140)

Wed Jan 8 11:47:03 PST 2025

https://github.com/gburgessiv updated https://github.com/llvm/llvm-project/pull/122140

>From dddfc636b14eee9e973a4cd30e3144a2753a1813 Mon Sep 17 00:00:00 2001
From: George Burgess IV <george.burgess.iv at gmail.com>
Date: Tue, 7 Jan 2025 15:48:40 -0700
Subject: [PATCH] [llvm][Docs] add discord bot capability notes

The LLVM Discord bot now has the ability to scrape the LLVM calendar &
send reminders about upcoming office hours events and sync-ups. Document
that here.

While I'm in the area, add a note about the bot's ability to @mention
people when they're on buildbot blamelists.

Related to llvm/Community.o#19
---
 llvm/docs/GettingInvolved.rst | 80 +++++++++++++++++++++++++++++++++--
 1 file changed, 76 insertions(+), 4 deletions(-)

diff --git a/llvm/docs/GettingInvolved.rst b/llvm/docs/GettingInvolved.rst
index edb3b5d9c2ad5b..99e8d1e4673848 100644
--- a/llvm/docs/GettingInvolved.rst
+++ b/llvm/docs/GettingInvolved.rst
@@ -214,6 +214,11 @@ what to add to your calendar invite.
      - `ics <https://drive.google.com/file/d/1ten-u-4yjOcCoONUtR4_AxsFxRDTUp1b/view?usp=sharing>`__
      - `Meeting details/agenda: <https://docs.google.com/document/d/1Glzy2JiWuysbD-HBWGUOkZqT09GJ4_Ljodr0lXD5XfQ/edit>`__
 
+
+For event owners, our Discord bot also supports sending automated announcements
+of upcoming sync-ups. Please see the :ref:`discord-bot-event-pings` section for
+info.
+
 Past online sync-ups
 ^^^^^^^^^^^^^^^^^^^^
 
@@ -355,6 +360,9 @@ The :doc:`CodeOfConduct` applies to all office hours.
     - `Google meet <https://meet.google.com/nga-uhpf-bbb>`__
     - English
 
+For event owners, our Discord bot also supports sending automated announcements
+of upcoming office hours. Please see the :ref:`discord-bot-event-pings` section
+for info.
 
 Guidance for office hours hosts
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -365,10 +373,11 @@ Guidance for office hours hosts
   :ref:`llvm-community-calendar`.
   Please see :ref:`llvm-community-calendar-host-guidance` for more guidance on
   what to add to your calendar invite.
-* When starting an office hours session, consider typing something like "*Hi,
-  I'm available for chats in the next half hour at* video chat URL. *I'm
-  looking forward to having conversations on the video chat or here.*" on the
-  the `#office-hours Discord channel <https://discord.com/channels/636084430946959380/976196303681896538>`__.
+* When starting an office hours session, if you haven't set up the Discord bot
+  integration, consider typing something like "*Hi, I'm available for chats in
+  the next half hour at* video chat URL. *I'm looking forward to having
+  conversations on the video chat or here.*" on the
+  `#office-hours Discord channel <https://discord.com/channels/636084430946959380/976196303681896538>`__.
 
   Doing this can help:
     * overcome potential anxiety to call in for a first time,
@@ -392,6 +401,60 @@ bot will update the channel with a link to a build bot when a build goes from
 passing to failing and again when the build goes from failing back to passing.
 It is a great way to actively monitor the status of the build.
 
+The bot also supports @mention-ing you when your email appears on a blamelist.
+For more details, DM ``help`` to the bot.
+
+.. _discord-bot-event-pings:
+
+Discord bot event pings
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Our Discord bot supports automatically sending messages about upcoming events
+on `the LLVM community calendar <https://calendar.google.com/calendar/u/0/embed?src=calendar@llvm.org>`_
+to Discord. This behavior is controlled on a per-event basis, by metadata in the
+event's description. Each piece of metadata should be on its own line in the
+event description.
+
+The currently supported metadata is:
+
+- ``discord-bot-event-type`` - **Required**. Specifies the event type. Valid
+  values are ``office-hours`` and ``sync-up``.
+- ``discord-bot-channels-to-mention`` - **Sometimes required**. A
+  comma-separated list of Discord channels to post notifications in. If your
+  ``discord-bot-event-type`` is ``office-hours``, the ``#office-hours`` channel
+  will be implicitly appended to this list (ergo, you don't need to specify this
+  item). Otherwise, you must specify a value here.
+- ``discord-bot-mention`` - **Optional**. A comma-separated list of people to
+  ping on each event notification. All names mentioned must be Discord
+  usernames, and must have a leading ``@``. e.g., ``@foo, @bar``.
+- ``discord-bot-reminder-time-before-start`` - **Optional**. The number of
+  minutes before the beginning of an event to send a ping. This should be
+  formatted as an integer. Defaults to 30.
+- ``discord-bot-message`` - **Optional**. Text to append to all event pings.
+
+An example of an event description with valid metadata is::
+
+  Regular office hours to chat with people about LLVM! We can help with
+  questions, troubleshooting bugs, etc.
+
+  discord-bot-channels-to-mention: #beginners, #foo
+  discord-bot-event-type: office-hours
+  discord-bot-mention: @gburgessiv, @bar
+  discord-bot-message: Come join us for office hours!
+  discord-bot-reminder-time-before-start: 5
+
+This metadata will prompt the Discord bot to:
+
+* send pings 5 minutes before the given event starts, mentioning ``@gburgessiv``
+  and ``@bar`` in the ping
+* send the pings to the ``#beginners``, ``#foo``, and ``#office-hours`` channels
+* include the text "Come join us for office hours!" in the ping
+
+A few minutes before sending a ping, the bot will double-check that the event
+hasn't been cancelled.
+
+If you need help troubleshooting, or have feature requests/questions, please
+feel free to ping @gburgessiv!
 
 .. _meetups-social-events:
 
@@ -485,6 +548,10 @@ Please put the following pieces of information in your calendar invite:
 * If you have meeting minutes for your event, add a pointer to where those live.
   A good place for meeting minutes could be as a post on LLVM Discourse.
 
+* If you're hosting a sync-up or office hours event and would like it to be
+  announced by the Discord bot, add the relevant metadata (full descriptions
+  available in the :ref:`discord-bot-event-pings` section).
+
 An example invite looks as follows
 
 .. code-block:: none
@@ -500,3 +567,8 @@ An example invite looks as follows
 
   Organizer(s): First Surname (name at email.com)
 
+  discord-bot-channels-to-mention: #lldb
+  discord-bot-event-type: sync-up
+  discord-bot-mention: @host-username, @another-host
+  discord-bot-message: Come join us to chat about LLDB!
+  discord-bot-reminder-time-before-start: 30

