Contributing to Bot
The purpose of this guide is to get you a running local version of the Python bot. You should have already forked the repository and cloned it to your local machine. If not, check out our detailed walkthrough.
This page will focus on the quickest steps one can take, with mentions of alternatives afterwards.
Setting up the project¶
Setup Project Dependencies¶
Below are the dependencies you must have installed to get started with the bot.
- Make sure you have Python 3.11 installed. It helps if it is your system's default Python version.
- Install Poetry.
- Install the project's dependencies.
- Docker CE
- Docker Compose. If you're using macOS and Windows, this already comes bundled with the previous installation. Otherwise, you can download it either from the website, or by running
pip install docker-compose.
If you get any Docker related errors, reference the Possible Issue section of the Docker page.
Set Up a Test Server¶
The Python bot is tightly coupled with the Python Discord server, so to have a functional version of the bot you need a server with channels it can use. It's possible to set the bot to use a single channel for all cogs, but that will cause extreme spam and will be difficult to work with.
You can start your own server and set up channels as you see fit, but for your convenience we have a template for a development server you can use: https://discord.new/zmHtscpYN9E3.
Keep in mind that this is not an exact mirror of the Python server, but a reduced version for testing purposes. The channels there are mostly the ones needed by the bot.
Set Up a Bot Account¶
You will need your own bot account on Discord to test your changes to the bot. See here for help with setting up a bot account. Once you have a bot account, invite it to the test server you created in the previous section.
It is 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.
Configure the Bot¶
You now have both the bot's code and a server to run it on. It's time for you to connect the two by setting the bot's configuration.
.env.server files we talk about below are ignored by git, so they do not get accidentally commit to the repository.
This file will contain sensitive information such as your bot's token, do not share it with anybody!
To start, create a
.env file in the project root with the below content.
BOT_TOKEN=YourDiscordBotTokenHere GUILD_ID=YourDiscordTestServerIdHere BOT_PREFIX=YourDesiredPrefixHere
Other values will be added to your
.env over time as you need to interact with other parts of the bot, but those are not needed for a basic setup. For a full list of support values see the ENV file option appendix
All server related configuration values are saved in this file, which also needs to be at the root directory of the project.
We provide a script to automatically generate a server config.
Note: The script only works with servers created with the template mentioned above.
If you want to setup the bot from an existing guild read out manual configuration guide. This is far more complicated and time consuming.
Running the below command will use the
GUILD_ID from the
.env file you created above to download all of the relevant IDs from the template guild into your
Note: This script will overwrite the
.env.server file. We suggest you put any configuration not generated by this script in to
$ poetry run task configure
Once the script has finished running, you'll notice the creation of a new file called
.env.server at your project's root directory.
This file will contain the extracted IDs from your server which are necessary for your bot to run.
Congratulations, you have finished the configuration and can now run your bot.
constants.pyto 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
.env.serverfile can remain in your local copy of the code, and will be ignored by commits via the project's
You are now almost ready to run the Python bot. The simplest way to do so is with Docker.
With all of the above setup, you can run The projec with
docker compose up. This will start the bot an all required services! Enter your server and type
!help (or whatever prefix you chose instead of
!) to see the bot in action!
Some other useful docker commands are as follows:
docker compose pullthis pulls updates for all non-bot services, such as postgres, redis and our site project!
docker compose buildthis 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.
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.
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
poetry 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.
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.
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.
Appendix: Full ENV File Options¶
The following is a list of all available environment variables used by the bot:
||Always||Your Discord bot account's token (see Set Up a Bot Account).|
||Always||Your Discord test server's id (see Set Up a Test Server).|
||When you wish to use a prefix different than "!"||Your Discord bot command's prefix.|
||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 (see Staring Redis with other methods).|
||When using Metricity||
||When you wish to interact with GitHub||The API key to interact with GitHub, for example to download files for the branding manager.|
||When you wish to interact with Metabase||The username for a Metabase admin account.|
||When you wish to interact with Metabase||The password for a Metabase admin account.|