Contributing to Bot
- Python 3.9
pip install poetry
- 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
Fork the project¶
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)
Test server and bot account¶
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.
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.
Configure the bot¶
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.|
||When connecting the bot to sentry||The DSN of the sentry monitor.|
||When you wish to see specific or all trace logs||Comma separated list that specifies which loggers emit trace logs through the listed names. If the ! prefix is used, all of the loggers except the listed ones are set to the trace level. If * is used, the root logger is set to the trace level.|
||When not using FakeRedis||The password to connect to the redis database. Leave empty if you're not using REDIS.|
If you are running on the host, while not required, we advise you set
true in your
config.yml 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
Run the project¶
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.
Run with Docker¶
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.
If you get any Docker related errors, reference the Possible Issues section of the Docker page.
Site and 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
Run on the host¶
Running on the host is particularly useful if you wish to debug the bot. The site has to have been started somehow beforehand.
poetry run task start
Working with Git¶
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.
Adding new statistics¶
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 explains how unittesting works, and how it fits in the context of our project.