From 455dc792d38766156747a156e14b75d28c211525 Mon Sep 17 00:00:00 2001 From: Boris Muratov <8bee278@gmail.com> Date: Sun, 17 Oct 2021 15:06:38 +0300 Subject: Restructure bot contributing guide (#591) * Restructure bot contributing guide Restructures the bot guide to focus on getting users "through the door" first, and slowly adding additional information and options. The guide is built in terms of showing ways to run the bot and how to achieve it, rather than listing all of the information for each configuration and environment variable right away. That said, the attempt was to still present the reader with the full information they need, and to still be able to use as a quick reference for contributors who are already familiar with the project. As a style choice, this guide incorporates collapsible elements, which required some CSS and JS additions. This could be resolved with the bulma-collapsible extension, but it doesn't seem to function well inside django templates. The guide includes an optional config.yml to use with the test server template. This is a temporary measure until we get the bootstrapping application going. This guide additionally splits the bot account creation and obtaining Discord ID's guides and they didn't seem related. The original file is kept for now as it is used by other guides at the moment. --- .../guides/pydis-guides/contributing/bot.md | 735 +++++++++++++++++---- .../contributing/creating-bot-account.md | 17 + .../contributing/obtaining-discord-ids.md | 42 ++ 3 files changed, 654 insertions(+), 140 deletions(-) create mode 100644 pydis_site/apps/content/resources/guides/pydis-guides/contributing/creating-bot-account.md create mode 100644 pydis_site/apps/content/resources/guides/pydis-guides/contributing/obtaining-discord-ids.md (limited to 'pydis_site/apps/content/resources') diff --git a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/bot.md b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/bot.md index 7419858e..4c09165d 100644 --- a/pydis_site/apps/content/resources/guides/pydis-guides/contributing/bot.md +++ b/pydis_site/apps/content/resources/guides/pydis-guides/contributing/bot.md @@ -2,206 +2,661 @@ title: Contributing to Bot description: A guide to setting up and configuring Bot. icon: fab fa-github -toc: 1 +toc: 3 --- - -# Requirements -* [Python 3.9](https://www.python.org/downloads/) -* [Poetry](https://github.com/python-poetry/poetry#installation) - * `pip install poetry` -* [Git](https://git-scm.com/downloads) - * [Windows](https://git-scm.com/download/win) - * [MacOS](https://git-scm.com/download/mac) or `brew install git` - * [Linux](https://git-scm.com/download/linux) -* A running webserver for the [site](../site) - * Follow the linked guide only if you don't want to use Docker or if you plan to do development on the site project too. - -## Using Docker - -Both the site and the bot can be started using Docker. -Using Docker is generally recommended (but not strictly required) because it abstracts away some additional set up work, especially for the site. -However, if you plan to attach a debugger to either the site or the bot, run the respective project directly on your system (AKA the _host_) instead. - -The requirements for Docker are: - -* [Docker CE](https://docs.docker.com/install/) -* [Docker Compose](https://docs.docker.com/compose/install/) (This already comes bundled on macOS and Windows, so you shouldn't need to install it) - * `pip install docker-compose` +The purpose of this guide is to get you a running local version of [the Python bot](https://github.com/python-discord/bot). +This page will focus on the quickest steps one can take, with mentions of alternatives afterwards. + +### Clone The Repository +First things first, to run the bot's code and make changes to it, you need a local version of it (on your computer). + +
If you don't have Git on your computer already, install it. You can additionally install a Git GUI such as GitKraken, or the GitHub CLI.
+To learn more about Git, you can look into our guides, as well as this cheatsheet, Learn Git Branching, and otherwise any guide you can find on the internet. Once you got the basic idea though, the best way to learn Git is to use it.
+Creating a copy of a repository under your own account is called a fork. This is where all your changes and commits will be pushed to, and from where your pull requests will originate from.
+ +If you used the provided server template, and you're not sure which channels belong where in the config file, you can use the config below. Pay attention to the comments with several # symbols, and replace the � characters with the right IDs.
+
+bot:
+ prefix: "!"
+
+ redis:
+ host: "redis"
+ password: null
+ port: 6379
+ use_fakeredis: true
+
+ stats:
+ presence_update_timeout: 300
+ statsd_host: "graphite.default.svc.cluster.local"
+
+urls:
+ # PyDis site vars
+ site: &DOMAIN "web:8000"
+ site_api: &API !JOIN [*DOMAIN, "/api"]
+ site_api_schema: "http://"
+ site_paste: &PASTE !JOIN ["paste.", "pythondiscord.com"]
+ site_schema: &SCHEMA "http://"
+ site_staff: &STAFF !JOIN [*DOMAIN, "/staff"]
+
+ paste_service: !JOIN ["https://", *PASTE, "/{key}"]
+ site_logs_view: !JOIN [*SCHEMA, *STAFF, "/bot/logs"]
+
+ # Snekbox
+ snekbox_eval_api: "http://localhost:8060/eval"
+
+##### << Replace the following � characters with the channel IDs in your test server >> #####
+# This assumes the template was used: https://discord.new/zmHtscpYN9E3
+dev_guild:
+ id: &DEV_GUILD_ID �
+
+ categories:
+ logs: &DEV_LOGS �
+ help_available: &DEV_HELP_AVAILABLE �
+ help_occupied: &DEV_HELP_OCCUPIED �
+ help_dormant: &DEV_HELP_DORMANT �
+ voice: &DEV_VOICE �
+
+ channels:
+ # Staff
+ admins_mods: &DEV_ADMINS_MODS �
+ lounge_helpers_org: &DEV_LOUNGE_HELPERS_ORG �
+ defcon: &DEV_DEFCON �
+ incidents: &DEV_INCIDENTS �
+ incidents_archive: &DEV_INCIDENTS_ARCHIVE �
+ staff_announcements: &DEV_STAFF_ANNOUNCEMENTS �
+ dev_logs: &DEV_DEV_LOGS �
+
+ # Logs
+ all_logs: &DEV_ALL_LOGS �
+ bb_logs: &DEV_BB_LOGS �
+ duck_pond: &DEV_DUCK_POND �
+
+ # Available Help Channels
+ how_to_get_help: &DEV_HTGH �
+
+ # Miscellaneous
+ bot_commands: &DEV_BOT_CMD �
+ general_meta_voice: &DEV_GMV �
+ dev_core_contrib: &DEV_DEV �
+
+ # Voice
+ voice-verification: &DEV_VOICE_VER �
+ vc: &DEV_VC �
+ staff_voice: &DEV_STAFF_VOICE �
+
+ # News
+ announcements: &DEV_ANNOUNCEMENTS �
+ py_news: &DEV_PY_NEWS �
+
+ # Off-topic
+ off_topic_0: &DEV_OT_0 �
+ off_topic_1: &DEV_OT_1 �
+ off_topic_2: &DEV_OT_2 �
+
+guild:
+ ##### << Replace the following � characters with the role and webhook IDs in your test server >> #####
+ roles:
+ announcements: �
+ contributors: �
+ help_cooldown: �
+ muted: &MUTED_ROLE �
+ partners: &PY_PARTNER_ROLE �
+ python_community: &PY_COMMUNITY_ROLE �
+ voice_verified: �
+
+ # Staff
+ admins: &ADMINS_ROLE �
+ core_developers: �
+ devops: �
+ domain_leads: �
+ helpers: &HELPERS_ROLE �
+ moderators: &MODS_ROLE �
+ mod_team: &MOD_TEAM_ROLE �
+ owners: &OWNERS_ROLE �
+ code_jam_event_team: �
+ project_leads: �
+
+ # Code Jam
+ team_leaders: �
+
+ # Streaming
+ video: �
+
+ webhooks:
+ big_brother: �
+ dev_log: �
+ duck_pond: �
+ incidents_archive: �
+ python_news: &PYNEWS_WEBHOOK �
+ talent_pool: �
+
+ ##### << At this point your test bot should be able to mostly work with your test server >> #####
+ # The following is the actual configs the bot uses, don't delete these.
+ id: *DEV_GUILD_ID
+ invite: "https://discord.gg/python"
+
+ categories:
+ help_available: *DEV_HELP_AVAILABLE
+ help_dormant: *DEV_HELP_DORMANT
+ help_in_use: *DEV_HELP_OCCUPIED
+ logs: *DEV_LOGS
+ voice: *DEV_VOICE
+
+ channels:
+ # Public announcement and news channels
+ announcements: *DEV_ANNOUNCEMENTS
+ change_log: *DEV_ANNOUNCEMENTS
+ mailing_lists: *DEV_ANNOUNCEMENTS
+ python_events: *DEV_ANNOUNCEMENTS
+ python_news: *DEV_PY_NEWS
+
+ # Development
+ dev_contrib: *DEV_DEV
+ dev_core: *DEV_DEV
+ dev_log: *DEV_DEV_LOGS
+
+ # Discussion
+ meta: *DEV_GMV
+ python_general: *DEV_GMV
+
+ # Python Help: Available
+ cooldown: *DEV_HTGH
+ how_to_get_help: *DEV_HTGH
+
+ # Topical
+ discord_py: *DEV_GMV
+
+ # Logs
+ attachment_log: *DEV_ALL_LOGS
+ message_log: *DEV_ALL_LOGS
+ mod_log: *DEV_ALL_LOGS
+ user_log: *DEV_ALL_LOGS
+ voice_log: *DEV_ALL_LOGS
+
+ # Off-topic
+ off_topic_0: *DEV_OT_0
+ off_topic_1: *DEV_OT_1
+ off_topic_2: *DEV_OT_2
+
+ # Special
+ bot_commands: *DEV_BOT_CMD
+ voice_gate: *DEV_VOICE_VER
+ code_jam_planning: *DEV_ADMINS_MODS
+
+ # Staff
+ admins: *DEV_ADMINS_MODS
+ admin_spam: *DEV_ADMINS_MODS
+ defcon: *DEV_DEFCON
+ duck_pond: *DEV_DUCK_POND
+ helpers: *DEV_LOUNGE_HELPERS_ORG
+ incidents: *DEV_INCIDENTS
+ incidents_archive: *DEV_INCIDENTS_ARCHIVE
+ mods: *DEV_ADMINS_MODS
+ mod_alerts: *DEV_ADMINS_MODS
+ mod_meta: *DEV_ADMINS_MODS
+ mod_spam: *DEV_ADMINS_MODS
+ mod_tools: *DEV_ADMINS_MODS
+ organisation: *DEV_LOUNGE_HELPERS_ORG
+ staff_lounge: *DEV_LOUNGE_HELPERS_ORG
+
+ # Staff announcement channels
+ admin_announcements: *DEV_STAFF_ANNOUNCEMENTS
+ mod_announcements: *DEV_STAFF_ANNOUNCEMENTS
+ staff_announcements: *DEV_STAFF_ANNOUNCEMENTS
+
+ # Voice Channels
+ admins_voice: *DEV_STAFF_VOICE
+ code_help_voice_1: *DEV_VC
+ code_help_voice_2: *DEV_VC
+ general_voice: *DEV_VC
+ staff_voice: *DEV_STAFF_VOICE
+
+ # Voice Chat
+ code_help_chat_1: *DEV_GMV
+ code_help_chat_2: *DEV_GMV
+ staff_voice_chat: *DEV_ADMINS_MODS
+ voice_chat: *DEV_GMV
+
+ # Watch
+ big_brother_logs: *DEV_BB_LOGS
+
+ moderation_categories:
+ - *DEV_LOGS
+
+ moderation_channels:
+ - *DEV_ADMINS_MODS
+
+ # Modlog cog ignores events which occur in these channels
+ modlog_blacklist:
+ - *DEV_ADMINS_MODS
+ - *DEV_ALL_LOGS
+ - *DEV_STAFF_VOICE
+
+ reminder_whitelist:
+ - *DEV_BOT_CMD
+ - *DEV_DEV
+
+ moderation_roles:
+ - *ADMINS_ROLE
+ - *MODS_ROLE
+ - *MOD_TEAM_ROLE
+ - *OWNERS_ROLE
+
+ staff_roles:
+ - *ADMINS_ROLE
+ - *HELPERS_ROLE
+ - *MODS_ROLE
+ - *OWNERS_ROLE
+
+##### << The bot shouldn't fail without these, but commands adding specific emojis won't work. >> #####
+# You should at least set the trashcan. Set the incidents emojis if relevant.
+style:
+ emojis:
+ badge_bug_hunter: "<:bug_hunter_lvl1:�>"
+ badge_bug_hunter_level_2: "<:bug_hunter_lvl2:�>"
+ badge_early_supporter: "<:early_supporter:�>"
+ badge_hypesquad: "<:hypesquad_events:�>"
+ badge_hypesquad_balance: "<:hypesquad_balance:�>"
+ badge_hypesquad_bravery: "<:hypesquad_bravery:�>"
+ badge_hypesquad_brilliance: "<:hypesquad_brilliance:�>"
+ badge_partner: "<:partner:�>"
+ badge_staff: "<:discord_staff:�>"
+ badge_verified_bot_developer: "<:verified_bot_dev:�>"
+
+ defcon_shutdown: "<:defcondisabled:�>"
+ defcon_unshutdown: "<:defconenabled:�>"
+ defcon_update: "<:defconsettingsupdated:�>"
+
+ failmail: "<:failmail:�>"
+
+ #incident_actioned: "<:incident_actioned:�>"
+ incident_investigating: "<:incident_investigating:�>"
+ incident_unactioned: "<:incident_unactioned:�>"
+
+ status_dnd: "<:status_dnd:�>"
+ status_idle: "<:status_idle:�>"
+ status_offline: "<:status_offline:�>"
+ status_online: "<:status_online:�>"
+
+ trashcan: "<:trashcan:�>"
+
+##### << Optional - If you don't care about the filtering and help channel cogs, ignore the rest of this file >> #####
+filter:
+ # What do we filter?
+ filter_domains: true
+ filter_everyone_ping: true
+ filter_invites: true
+ filter_zalgo: false
+ watch_regex: true
+ watch_rich_embeds: true
+
+ # Notify user on filter?
+ # Notifications are not expected for "watchlist" type filters
+ notify_user_domains: false
+ notify_user_everyone_ping: true
+ notify_user_invites: true
+ notify_user_zalgo: false
+
+ # Filter configuration
+ offensive_msg_delete_days: 7 # How many days before deleting an offensive message?
+ ping_everyone: true
+
+ # Censor doesn't apply to these
+ channel_whitelist:
+ - *DEV_ADMINS_MODS
+ - *DEV_BB_LOGS
+ - *DEV_ALL_LOGS
+ - *DEV_LOUNGE_HELPERS_ORG
+
+ role_whitelist:
+ - *ADMINS_ROLE
+ - *HELPERS_ROLE
+ - *MODS_ROLE
+ - *OWNERS_ROLE
+ - *PY_COMMUNITY_ROLE
+ - *PY_PARTNER_ROLE
+
+help_channels:
+ enable: true
+
+ # Minimum interval before allowing a certain user to claim a new help channel
+ claim_minutes: 1
+
+ # Roles which are allowed to use the command which makes channels dormant
+ cmd_whitelist:
+ - *HELPERS_ROLE
+
+ # Allowed duration of inactivity before making a channel dormant
+ idle_minutes: 1
+
+ # Allowed duration of inactivity when channel is empty (due to deleted messages)
+ # before message making a channel dormant
+ deleted_idle_minutes: 1
+
+ # Maximum number of channels to put in the available category
+ max_available: 2
+
+ # Maximum number of channels across all 3 categories
+ # Note Discord has a hard limit of 50 channels per category, so this shouldn't be > 50
+ max_total_channels: 20
+
+ # Prefix for help channel names
+ name_prefix: 'help-'
+
+ # Notify if more available channels are needed but there are no more dormant ones
+ notify: true
+
+ # Channel in which to send notifications
+ notify_channel: *DEV_LOUNGE_HELPERS_ORG
+
+ # Minimum interval between helper notifications
+ notify_minutes: 5
+
+ # Mention these roles in notifications
+ notify_roles:
+ - *HELPERS_ROLE
+
+##### << Add any additional sections you need to override from config-default.yml >> #####
+
+
+config-default.yml to match your server, it is heavily discouraged.
+ This file's purpose is to provide the configurations the Python bot needs to run in the Python server in production, and should remain as such.
+ In contrast, the config.yml file can remain in your local copy of the code, and will be ignored by commits via the project's .gitignore.
+ pip install docker-compose.If you get any Docker related errors, reference the Possible Issue section of the Docker page.
+poetry run task start, or directly python -m bot.Edit Configurations and set everything according to this image: 
launch.json create a new Python configuration, and set the name of the program to be run to bot. VSC will correctly run it as a module.