Before contributing, please ensure you read the contributing guidelines in full.

Requirements¶

• Python 3.9
• Poetry
• Git
  • Windows Installer
  • MacOS Installer or brew install git
  • Linux

Using Gitpod¶

Sir Lancebot can be edited and tested on Gitpod. Gitpod will automatically install the correct dependencies and Python version, so you can get straight to coding.

To do this, you will need a Gitpod account, which you can get here, and a fork of Sir Lancebot. This guide covers forking the repository here.

Afterwards, click on this link to spin up a new workspace for Sir Lancebot. Then run the following commands in the terminal after the existing tasks have finished running:

git remote rename origin upstream
git add remote origin https://github.com/{your_username}/sir-lancebot

Make sure you replace {your_username} with your Github username. These commands will set the Sir Lancebot repository as the secondary remote, and your fork as the primary remote. This means you can easily grab new changes from the main Sir Lancebot repository.

Once you've set up a test server and bot account and your environment variables, you are ready to begin contributing to Sir Lancebot!

Using Docker¶

Sir Lancebot can be started using Docker. Using Docker is generally recommended (but not strictly required) because it abstracts away some additional set up work.

The requirements for Docker are:

• Docker CE
• Docker Compose
  • pip install docker-compose
  • This is only a required step for linux. Docker comes bundled with docker-compose on Mac OS and Windows.

Fork the Project¶

You will need your own remote (online) copy of the project repository, known as a fork.

• Learn how to create a fork of the repository here.

You will do all your work in the fork rather than directly in the main repository.

Development Environment¶

1. Once you have your fork, you will need to clone the repository to your computer.
2. After cloning, proceed to install the project's dependencies. (This is not required if using Docker)

Test Server and Bot Account¶

You will need your own test server and bot account on Discord to test your changes to the bot.

1. Create a test server.
2. Create a bot account and invite it to the server you just created.
3. Create the following text channels:
   • #announcements
   • #dev-log
   • #sir-lancebot-commands
4. Create the following roles:
   • @Admin
5. Note down the IDs for your server, as well as any channels and roles created.
   • Learn how to obtain the ID of a server, channel or role here.

Environment variables¶

You will have to setup environment variables:

• Learn how to set environment variables here.

The following variables are needed for running Sir Lancebot:

Full environment variable reference for this project.

While not required, we advise you set USE_FAKEREDIS to true in 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, please see the below linked guide for Redis related variables.

Run the project¶

The sections below describe the two ways you can run this project. We recommend Docker as it requires less setup.

Run with Docker¶

Make sure to have Docker running, then use the Docker command docker-compose up in the project root. The first time you run this command, it may take a few minutes while Docker downloads and installs Sir Lancebot's dependencies.

$ docker-compose up

If you get any Docker related errors, reference the Possible Issues section of the Docker page.

Run on the host¶

After installing project dependencies use the poetry command poetry run task start in the project root.

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

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

Have fun!