diff options
| -rw-r--r-- | bot/exts/backend/branding/_cog.py | 24 | ||||
| -rw-r--r-- | bot/exts/backend/branding/_repository.py | 21 |
2 files changed, 43 insertions, 2 deletions
diff --git a/bot/exts/backend/branding/_cog.py b/bot/exts/backend/branding/_cog.py index 1c8ea1f05..7519f029e 100644 --- a/bot/exts/backend/branding/_cog.py +++ b/bot/exts/backend/branding/_cog.py @@ -76,7 +76,29 @@ def extract_event_name(event: Event) -> str: class Branding(commands.Cog): - """Guild branding management.""" + """ + Guild branding management. + + This cog is responsible for automatic management of the guild's branding while sourcing assets directly from + the branding repository. + + We utilize multiple Redis caches to persist state. As a result, the cog should seamlessly transition across + restarts without having to query either the Discord or GitHub APIs, as it will always remember which + assets are currently applied. + + Additionally, the state of the icon rotation is persisted. As a result, the rotation doesn't reset unless + the current event or its icons change. + + The cog is designed to be autonomous. The daemon, unless disabled, will poll the branding repository at + midnight every day and respond to detected changes. Since we persist SHA hashes of tracked assets, + changes in an on-going event will trigger automatic resynchronisation. + + A #changelog notification is automatically sent when entering a new event. Changes in the branding of + an on-going event do not trigger a repeated notification. + + The command interface allows moderators+ to control the daemon or request an asset synchronisation, + while regular users can see information about the current event and the overall event schedule. + """ # RedisCache[ # "daemon_active": If True, daemon auto-starts; controlled via commands (bool) diff --git a/bot/exts/backend/branding/_repository.py b/bot/exts/backend/branding/_repository.py index 2f96396c0..a612b6752 100644 --- a/bot/exts/backend/branding/_repository.py +++ b/bot/exts/backend/branding/_repository.py @@ -69,7 +69,26 @@ class Event(t.NamedTuple): class BrandingRepository: - """Abstraction exposing the branding repository via convenient methods.""" + """ + Branding repository abstraction. + + This class represents the branding repository's main branch and exposes available events and assets as objects. + + The API is primarily formed by the `get_current_event` function. It performs the necessary amount of validation + to ensure that a misconfigured event isn't returned. Such events are simply ignored, and will be substituted + with the fallback event, if available. + + Warning logs will inform core developers if a misconfigured event is encountered. + + Colliding events cause no special behaviour - in such cases, the first found active event is returned. + We work with the assumption that the branding repository checks for such conflicts and prevents them + from reaching the main branch. + + This class keeps no internal state. All `get_current_event` calls will result in GitHub API requests. + The caller is therefore responsible for being responsible and caching information to prevent API abuse. + + Requests are made using the HTTP session looked up on the bot instance. + """ def __init__(self, bot: Bot) -> None: self.bot = bot |