This is guide on how to set up a working development environment for this project with Visual Studio Code. While this guide is primarily targeted towards those on Windows, tips for Debian/Ubuntu users will also be provided.

Visual Studio Code is a flexible IDE, well suited to being customized for each developer's needs. Install it from their website here.

Debian/Ubuntu users should download the .deb file and then use sudo apt install ./<file>.deb to install it

Since we are going to be doing Python development, we need the Python extension pack, a collection of development and error detection tools that help us write good Python code. Once you have Visual Studio Code installed, open the extension tab on the left (ctrl+shift+X), and use the search bar to find and install Python by Microsoft.

Another tool we will be using heavily is Git, a near-universal version control tool that will allow us to collaborate and track changes made to our project. Install it here.

Debian/Ubuntu users should have it already installed on their system. Use git --version to check if its installed and if not use sudo apt update and sudo apt install git to install it.

Select Terminal>New Terminal or use ctrl+shift+` to open a terminal in Visual Studio Code. Use the following commands to set up git to sign commits with your email and name:

git config --global user.name "John Doe"
git config --global user.email [email protected]

Windows users, for some reason Visual Studio Code often uses Powershell as its default profile. Powershell recognizes different commands from the Command Prompt, and will result in many commands in this guide to not work. To fix this, follow the below images to change the default profile to Command Prompt and restart the terminal:

You can clone the repository in many ways, one easy way is:

git clone https://github.com/ColoradoSchoolOfMines/acm-discord-bot.git

Note: this clones the repository into your current working directory. I recommend cloning repositories into Documents/GitHub, as it keeps things organized and consistent with GitHub Desktop.

Install the latest version of Python here. Make sure that in the installation settings Python is added to the PATH, so that Windows will recognize when you use Python commands. When you are done open a terminal ctrl+shift+` and execute python --version to verify you have Python installed.

Debian/Ubuntu users use sudo apt install python3

If you open up requirements.txt, you will see that our project is dependent on a handful of python libraries. You could install these directly, but I would recommend setting up a virtual environment for your project. After opening the repository in Visual Studio Code, open a terminal ctrl+shift+` and execute:

python -m venv environment

Currently the project is expected to run on Python3.8+. Using the most recent version of Python will likely work fine, as long as you avoid the new language features added since then. If you want to avoid worrying about that, also install Python3.8 without adding it to the PATH and use virtualenv:

pip install virtualenv
virtualenv -p <PATH/TO/python3.8> environment

Once created, use the following series of commands to activate your environment and install dependencies:

Windows

environment\Scripts\activate.bat
pip install -r requirements.txt

Debian/Ubuntu

source environment/bin/activate
pip install -r requirements.txt

Take note of pip install -r requirements.txt. You will use this command again if a commit changes requirements.txt. If you are adding or updating dependencies, use pip freeze > requirements.txt to change requirements.txt accordingly.

At this point you should be finished with installing and configuring software. Now all that is left is to create a test Discord bot for it to connect to. Log in to the Discord Developer Portal, and make a New Application:

Navigate to the Bot tab and add a bot to your application. Public Bot should be set to off since we don't want other people inviting our test bot to random servers.

Select the OAuth2 tab and navigate to the URL Generator. This is how you configure the permissions given to your bot from the created invite. Give the bot the below permissions and paste the resulting link into your browser to invite the bot to a testing server.

If you navigate to run.py in Visual Studio Code, there should be a run button around the top right. Click it and you should get the following error:

AssertionError: The env "DEBUG_TOKEN" is unexpectedly empty

The file .env stores environmental variables that we might not want public knowledge. A major one of these is the Discord bot token. With this token anyone can connect to the bot and run whatever code they want on it. Because of this, the token for the deployed ACMBot will be kept private and to test our code we instead use the testing bot we just created.

A template '.env' file should have been created automatically. Look for it in the folder static inside the project directory. The static folder holds all data files that remain constant during code execution. The file contents should look something like this:

# Environmental variables for project
TOKEN=
DEBUG_TOKEN=
DEBUG_GUILDS=

Go back to the Discord Developer Portal. Under the Bot tab, select Reset Token and paste the result after DEBUG_TOKEN=.

Now run run.py again. The bot should now start up successfully. Stop the bot with ctrl+c in the terminal and you should see a new file appear called discord.log. Open that file and you will be able to see log data from both our code and its dependencies. You should see that the bot has connected to at least 1 guild/server, that being the testing server you invited it to. Paste the numerical guild id behind DEBUG_GUILDS= in .env.

DEBUG_GUILDS is a list of servers that the bot tells Discord the bot is being tested on. Slash commands will register faster on these servers, and a debug only command /refresh will appear, allowing parts of the bot's code to be hot reloaded while the bot is still online.

You should now be able to develop and test the project. Next steps would be to consult the Pycord Guide for information on the project's main library, check out the example cog test.py, and create a new branch to start making contributions to the repository.