Contributing to Bot

This guide will walk you through setting up and running the Python bot locally, and get you ready to contribute to it.

Setting up the project

Install Project Requirements

The following are needed to run the bot. Follow the links for installation instructions.

Set Up a Development Environment

To start, ensure you have forked and cloned the bot repository to your local machine. For help with this, check out our forking and cloning guide.

From the root of the cloned repository, run the following command to install the project dependencies:

$ uv sync

You should also install our pre-commit hooks, which will lint your code before you commit it.

$ uv run task precommit

Set Up a Test Server

The Python bot is tightly coupled with the Python Discord server, so the bot expects the existence of certain channels, roles, and other server configurations to be able to run.

It is highly recommended to use our server template, as it allows most configuration to be automatically generated for you.

This is not an exact mirror of the Python server, but a reduced version for testing purposes.

Set Up a Bot Account

You will need your own bot account on Discord to test your changes to the bot. See our guide for help with setting up a bot account, and inviting it to your server.

If you want to use an existing test bot account, ensure that:

  • It has the Server Members Intent and Message Content Intent intents enabled.
  • It was invited to your server with the bot scope and Administrator permission.

Configure the Bot

The bot reads variables for configuration from two files, .env, and .env.server. These files are ignored by git, as they contain information specific to your local environment.

.env

Create a file called .env in the project root with the below content, and insert your bot token and guild ID. Remember that your bot token is sensitive information, and should not be shared with anyone.

BOT_TOKEN=YourDiscordBotTokenHere
GUILD_ID=YourDiscordTestServerIdHere

See here for help with obtaining the bot token, and here for help with obtaining the guild's ID.

This is all that is needed for a basic setup. See the appendix for a full list of available variables.

.env.server

This file is automatically generated by our bootstrap script, which connects to your server and extracts configuration needed for the bot to run.

To run the script, execute the following command in the project root:

$ uv run task configure

Note: The script only works with servers created with the template mentioned above. To configure the bot manually, see our manual configuration guide.

Note: This script will overwrite the .env.server file. We suggest you put any configuration not generated by this script in to .env instead.

Ensure that this runs successfully, and that the .env.server file is created in the project root.

Congratulations, you have finished the configuration and can now run your bot.

Run it!

You are now ready to run the bot. The simplest way to do so is with Docker.

Start the project by running the command docker compose up. This will start the bot and all required services! Enter your server and type !help to see the bot in action!

Some other useful docker commands are as follows:

  1. docker compose pull this pulls updates for all non-bot services, such as postgres, redis and our site project!
  2. docker compose build this rebuilds the bot's docker image, this is only needed if you need to make changes to the bot's dependencies, or the Dockerfile itself.

Your bot is now running, all inside Docker.

Note: If you want to read about how to make debugging with an IDE a easier, or for additional running methods, check out our extended configuration guide.

If you encounter issues with docker, check out our docker guide, which lists some common issues and their solutions.

Development Tips

Now that you have everything setup, it is finally time to make changes to the bot!

Working with Git

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.

Running tests

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.

Make sure to run tests before pushing code.

Even if you run the bot through Docker, you might want to setup a development environment in order to run the tests locally.

Lint before you push

As mentioned in the contributing guidelines, you should make sure your code passes linting for each commit you make.

For ease of development, you can install the pre-commit hook with uv run task precommit, which will check your code every time you try to commit it. For that purpose, even if you run the bot through Docker, you might want to setup a development environment, as otherwise the hook installation will fail.

Issues?

If you have any issues with setting up the bot, come discuss it with us on the #dev-contrib channel on our server.

If you find any bugs in the bot or would like to request a feature, feel free to open an issue on the repository.

Next steps

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.

Have fun!

Appendix: Full ENV File Options

The following is a list of all available environment variables used by the bot:

Variable Required Description
BOT_TOKEN Always Your Discord bot account's token (see Set Up a Bot Account).
GUILD_ID Always Your Discord test server's id (see Set Up a Test Server).
BOT_PREFIX When you wish to use a prefix different than "!" Your Discord bot command's prefix.
API_KEYS_SITE_API 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.
BOT_SENTRY_DSN When connecting the bot to sentry The DSN of the sentry monitor.
BOT_TRACE_LOGGERS 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.
DEBUG In production true or false, depending on whether to enable debug mode, affecting the behavior of certain features. true by default.
REDIS_PASSWORD When not using FakeRedis The password to connect to the Redis database (see Staring Redis with other methods).
USE_METRICITY When using Metricity true or false, depending on whether to enable metrics collection using Metricity (see Working with Metricity). false by default.
API_KEYS_GITHUB When you wish to interact with GitHub The API key to interact with GitHub, for example to download files for the branding manager.
METABASE_USERNAME When you wish to interact with Metabase The username for a Metabase admin account.
METABASE_PASSWORD When you wish to interact with Metabase The password for a Metabase admin account.

Table of Contents