CONTRIBUTING.md

Villager Bot Contribution Guide

Setting up the development environment

1. Install Git
2. Install PostgreSQL
3. Install Python 3.10+
4. Install Poetry with Pip
   • Windows: py -m pip install poetry
   • Linux/Mac: python3 -m pip install poetry
5. Git clone this repo or your fork
   • Example: git clone https://github.com/Iapetus-11/Villager-Bot
6. Install dependencies with Poetry using the command poetry install
   • This must be done from project's top folder (the folder which contains the pyproject.toml file)
7. Create a database and execute the contents of the setup.sql
8. Create a secrets.json file in the bot/ folder based off of bot/secrets.example.json
   • The Discord bot token can be generated by following these steps
   • The google search keys are optional (they're used for the !!google, !!youtube, and !!image search commands)
   • The xapi key is optional (it's used for the !!nametoxuid command)
   • The Fernet key can be generated using the cryptography module, see this example
9. Create a secrets.json file in the karen/ folder based off of karen/secrets.example.json
   • The cluster count should be set to 1 unless you plan to run multiple clusters with Docker
   • The shard count must be a multiple of the cluster count
   • The top.gg fields do not need to be filled out
10. (Optional if using Docker to run multiple clusters) Create a .env file based off of the .env.example file

Running Villager Bot

Villager Bot is split into two components, Karen and the clusters. A "cluster" is a group of shards (websockets connected to Discord in this case). These clusters need to share state and communicate, which is what Karen facilitates. To run Villager Bot you must run both Karen and at least one cluster.

Windows

1. Run Karen with poetry run py -m karen in one terminal/command prompt/powershell instance/window
2. Run a cluster with poetry run py -m bot in another instance/window

Linux/Mac

1. Run Karen with poetry run python3 -m karen in one terminal window
2. Run a cluster with poetry run python3 -m bot in another terminal window

PyCharm

1. Create run configurations for both Karen and a cluster
   • Both need to be ran as modules (using the -m flag like -m bot or -m karen) otherwise issues will occur
2. Click the run/debug buttons

Docker

1. Build the docker images with docker compose build
2. Run Villager Bot with docker compose up

Contributing

• Before contributing please discuss your proposed changes in the Discord server
• Please open a PR (pull request) to have your changes reviewed and merged
• You should run the format_and_lint script (poetry run format_and_lint) provided to format (and lint) your code prior to submitting your PR or the PR checks will fail

Technical discussion/questions/help

• Please join the Discord server and use the #💻tech-talk channel