Contributing to Bot
This project is responsible for maintaining the Discord Bot in our Discord community. Our members and staff rely on it on a daily basis. It adds conveniences for our members when using the community, as well as being a core of our moderation toolkit.
The bot is built with
discord.py and has features relying on our site and snekbox projects.
- Python 3.8
pip install pipenv
- A running webserver for the 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.
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
- Docker Compose (This already comes bundled on macOS and Windows, so you shouldn't need to install it)
pip install docker-compose
You will need access to a copy of the git repository of your own that will allow you to edit the code and push your commits to. 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 PRs will originate from.
For any staff member, since you have write permissions already to the original repository, you can just create a feature branch to push your commits to instead.
- Clone your fork to a local project directory
- Install the project's dependencies
- Prepare your hosts file (Optional)
You will need your own test server and bot account on Discord to test your changes to the bot.
discord.py 1.5 and later, it is now necessary to explicitly request that your Discord bot receives certain gateway events. The Python bot requires the
Server Member Intent to function. In order to enable it, visit the Developer Portal (from where you copied your bot's login token) and scroll down to the
Privileged Gateway Intents section. The
Presence Intent is not necessary and can be left disabled.
If your bot fails to start with a
PrivilegedIntentsRequired exception, this indicates that the required intent was not enabled.
Setup categories, channels, emojis, roles, and webhooks in your server. To see what needs to be added, please refer to the following sections in the
We understand this is tedious and are working on a better solution for setting up test servers. In the meantime, here is a template for you to use.
You will need to copy IDs of the test Discord server, as well as the created channels and roles to paste in the config file. If you're not sure how to do this, check out the information over here.
- Create a copy of
config.ymlin the same directory.
guild.idto your test servers's ID.
- Change the IDs in the sections mentioned earlier to match the ones in your test server.
- If running the webserver in Docker, set it to
- If the site container is running separately (i.e. started from a clone of the site repository), then COMPOSE_PROJECT_NAME has to be set to use this domain. If you choose not to set it, the domain in the following step can be used instead.
- If running the webserver locally and the hosts file has been configured, set it to
- Otherwise, use whatever domain corresponds to the server where the site is being hosted.
- If running the webserver in Docker, set it to
urls.site_apito whatever value you assigned to
apiprefixed to it, for example if you set
- Setup the environment variables listed in the section below.
These contain various settings used by the bot. To learn how to set environment variables, read this page first.
The following is a list of all available environment variables used by the bot:
||Always||Your Discord bot account's token (see Test server and bot account).|
||When running bot without Docker||Used to authenticate with the site's API. When using Docker to run the bot, this is automatically set. By default, the site will always have the API key shown in the example below.|
||reddit cog||OAuth2 client ID for authenticating with the reddit API.|
||reddit cog||OAuth2 secret for authenticating with the reddit API. Leave empty if you're not using the reddit API.|
||When connecting the bot to sentry||The DSN of the sentry monitor.|
||When not using FakeRedis||The password to connect to the redis database. Leave empty if you're not using REDIS.|
truein the config file during development to avoid the need of setting up a Redis server. It does mean you may lose persistent data on restart but this is non-critical. Otherwise, you should set up a Redis instance and fill in the necessary config.
BOT_TOKEN=YourDiscordBotTokenHere BOT_API_KEY=badbot13m0n8f570f942013fc818f234916ca531 REDDIT_CLIENT_ID=YourRedditClientIDHere REDDIT_SECRET=YourRedditSecretHere
The bot can run with or without Docker. When using Docker, the site, which is a prerequisite, can be automatically set up too. If you don't use Docker, you have to first follow the site guide to set it up yourself. The bot and site can be started using independent methods. For example, the site could run with Docker and the bot could run directly on your system (AKA the host) or vice versa.
The following sections describe how to start either the site, bot, or both using Docker. If you are not interested in using Docker, see this page for setting up the site and this section for running the bot.
This method will start both the site and the bot using Docker.
Start the containers using Docker Compose while inside the root of the project directory:
-d option can be appended to the command to run in detached mode. This runs the containers in the background so the current terminal session is available for use with other things.
This method will start only the site using Docker.
docker-compose up site
See this section for how to start the bot on the host.
This method will start only the bot using Docker. The site has to have been started somehow beforehand.
Start the bot using Docker Compose while inside the root of the project directory:
docker-compose up --no-deps bot
Running on the host is particularily useful if you wish to debug the bot. The site has to have been started somehow beforehand.
pipenv run start
Now that you have everything setup, it is finally time to make changes to the bot! If you have not yet read the contributing guidelines, now is a good time. Contributions that do not adhere to the guidelines may be rejected.
Notably, version control of our projects is done using Git and Github. It can be intimidating at first, so feel free to ask for any help in the server.
Details on how to add new statistics can be found on the statistic infrastructure page. We are always open to more statistics so add as many as you can!
This section of the README in the
tests repository will explain how to run tests. The whole document explain how unittesting work, and how does it fit in our context.