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 and has features relying on our site and snekbox projects.

This guide is new and is the process of testing and refinement. If you have any troubles following it, let staff know!


  • Python 3.8
  • Pipenv
    • pip install pipenv
  • Git
  • 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.

Using Docker

Both the site and the bot can be started using Docker. Using Docker is generally recommended (but not stricly 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:

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 Core Developers, since you have write permissions already to the original repository, you can just create a feature branch to push your commits to instead.

Development environment

  1. Clone your fork to a local project directory
  2. Install the project's dependencies
  3. 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.

Server Setup

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 config-default.yml file:

  • style.emojis
  • guild.categories
  • guild.channels
  • guild.roles
  • guild.webhooks

We understand this is tedious and are working on a better solution for setting up test servers.

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.

  1. Create a copy of config-default.yml named config.yml in the same directory.
  2. Set to your test servers's ID.
  3. Change the IDs in the sections mentioned earlier to match the ones in your test server.
  4. Set urls.site_schema to "http://".
  5. Set
    • If running the webserver in Docker, set it to "web:8000".
      • 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 "pythondiscord.local:8000".
    • Otherwise, use whatever domain corresponds to the server where the site is being hosted.
  6. Setup the environment variables listed in the section below.

Environment variables

These contain various settings used by the bot. To learn how to set environment variables, read this page first.

The following is a table of all available environment variables used by the bot. Even if an environment variable is not strictly required, it should still be given some value (a dummy value is fine if you don't plan on using the associated feature).

Variable Required Description
BOT_TOKEN Always Your Discord bot account's token (see Test server and bot account).
BOT_API_KEY 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_CLIENT_ID reddit cog OAuth2 client ID for authenticating with the reddit API.
REDDIT_SECRET reddit cog OAuth2 secret for authenticating with the reddit API.

Example .env file:


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:

docker-compose up

The -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.

Site only

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.

Bot only

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 particularily useful if you wish to debug the bot. The site has to have been started somehow beforehand.

pipenv run 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.

Click here to see the basic Git workflow when contributing to one of our projects.

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!

Have fun!