Skip to content

How To Contribute Code

Jump to bottom
Isaac Beh edited this page May 22, 2024 · 1 revision

The following provides a rough guide on how to build a test copy of the bot and contribute to the source code. If you're stuck at any step, need some help or unsure of any of these instructions, please ask on the UQCS Discord. The infra team are more than happy to help and are always excited to see new contributors!

Building & Running UQCSbot Locally

The following steps require python 3.10 or above to be installed on your path. To test the version of python you currently have, in the terminal, run

python --version

or

python3 --version

You will also need pip. Usually this is installed with python, but can be installed separately (see here). To check if you have pip, run:

pip --version

Getting a Bot Token (First Time Only)

In order to run a test instance of UQCSbot, you will need to get a bot token through discord.

  1. Log in to the Discord Developer Portal.

  2. Click on "New Application"

  1. Name the application. Try to pick a unique name like "UQCSbot-your-name" to avoid confusion if there are multiple bots.

  2. Click on "OAuth2" then "URL Generator". Select the option for "Bot".

  1. Select the relevant permissions needed for the bot features you are interested in. Some standard permissions can be seen below.

  1. Go to the URL given at the bottom of the page to add the bot to a testing server (note: do not test on the UQCS main server). There is an official UQCS testing server. Ask committee if you want access (or you can create a discord server yourself).

  2. To get your bot token, go back to the developer portal go to "Bot" and click "Reset Token". This will provide you with your bot's token.

  3. In the Bot section of the developer portal, scroll down and enable all "Privileged Gateway Intents".

  4. Whilst not necessary, it is also good to enable Developer Mode on your discord account to be able to copy message and server IDs when needed. This is done through the Discord application, under "App Settings" > "Advanced" > "Developer Mode".

Downloading UQCSbot & Related Tools (First Time Only)

  1. Open up a terminal with the working directory where you want to save the bot. Run the command:
git clone https://github.com/UQComputingSociety/uqcsbot-discord.git
  1. Install poetry which UQCSbot uses for dependency management. After you have set up poetry, to get all the required libraries, within the folder containing UQCSbot run the command:
poetry install

Setting Up The Environment (First Time Only)

  1. Copy the .env.example to a new file called .env. This file will contain all environment variables. We will only fill in the required variables for running the bot, as the others relate to specific parts of the bot (e.g. starboard or the minecraft server). If you do need more information about the environment variables, it can can be found here.

  2. Enter the following:

    1. The Discord bot token from Discord Developer Portal (see above) after DISCORD_BOT_TOKEN=.

    2. The server ID of the testing server you are using after SERVER_ID. If you have developer mode activated on your discord account (see Getting a Bot Token step 9 above), you can get this right clicking on a server icon and choosing "Copy Server ID".

Running UQCSbot

  1. Within the folder of your copy of UQCSbot, run the command:
poetry run botdev

The bot should be active in the server that it is connected to.

  1. To shut down the bot, press CTRL-C.

Contributing Code To UQCSbot

The following steps will help you contribute new code to UQCSbot. The following steps require git. If you feel confident with git, the sections of importance are "Formatting Code", "Running Automated Tests", "Static Type Checking".

Creating A New Fork

  1. From the UQCSbot GitHub page, click "Fork", then "Create Fork" on the next page.
  1. Follow the steps from "Downloading UQCSbot & Related Tools" (above), but this time use the URL from your fork.

  1. Repeat the "Setting Up The Environment" steps (above). Also feel free to run the bot (using the steps from "Running UQCSbot" above) to ensure everything is working.

  2. Optional: Branches allow you to organise what you are working on. In a terminal within the folder of your fork of UQCSbot, you can create a new branch using:

git branch new-branch-name-here

To be working on this branch (or to work on a different branch, run:

git checkout branch-name-you-want

Making Changes

Edit the files you want. You can continue to test the bot by repeating the steps for "Running UQCSbot" (above). Also note that the bot command group /managecogs can help you reload files without having to restart the bot.

Formatting Code

UQCSbot's code should all follow the standard set by black, and will be checked when you try to do a PR. Code can be autoformatted to meet specification by running:

poetry run black uqcsbot

A specific file can be formatted by running:

poetry run black uqcsbot\file-name.py

Formatting should be done before every commit if possible.

Running Automated Tests

UQCSbot's code should pass all the tests contained in uqcsbot\tests\, and all tests will be checked when you try to do a PR. Tests can be checked locally by running:

poetry run pytest tests

A specific test file can be run by running:

poetry run pytest tests\test-file-name.py

Static Type Checking

To try to keep UQCSbot maintainable, all new files are analyzed by pyright. Static type checking needs to pass when you try to do a PR. You can test locally by running:

poetry run pyright uqcsbot

A specific test file can be run by running:

poetry run pyright uqcsbot\file-name.py

Publishing Changes

Once you are happy with your changes, theses steps will let you create a pull request (PR) so that someone can double check your code.

  1. When you run
git status

you should see files under Changes not staged for commit and/or Untracked files. Specifically, these should be the files you modified or added. To confirm that these are the changes you want to publish, run

git add .

or if you only want to confirm some of the files, run

git add file-path-here
  1. To "commit" these changes (i.e. save these changes as a step in UQCSbot's history), run:
git commit -m "commit message here"

The commit message should be a short (~80 characters) message about the changes you made. You will have the change when you complete your PR to write more details, so keep this message brief.

Note that you can repeat steps 1 and 2 many times before the next steps if you want to continue to make changes. Commits are just like points that people can jump back to in history.

  1. To have these changes not only on your computer, but also on GitHub, run:
git push

Note that the first time you do this, you might have an error appear about the current branch not having an upstream branch. If this is the case, run

git push --set-upstream origin your-current-branch-name
  1. On GitHub, go to the "Pull requests" tab of the UQCSbot repository and click "New pull request". Click the "compare across forks option" and choose your fork and branch for the "Head repository". Then click "Create pull request".

  1. Fill in the details of the PR. Use the right sidebar to add relevant labels.

  2. Wait for someone to review your code. This can take some time, so feel free to ask about this on Discord.

  3. The reviewer might suggest some changes. Don't worry, this isn't a judgement of your coding ability, nor does it mean that your changes aren't wanted. You can discuss comments on GitHub or Discord. Once you've made changes, repeat steps 1, 2 and 3. You should see your commits appear automatically within the PR. Further commits may need to be approved as well. This can take some time, so do be patient.

If at any point someone else makes changes, you may need to run

git fetch

then

git pull

to keep the copy on your computer up to date.

  1. Once the changes have been approved (usually by 2 different reviewers), your changes will be merged into the main branch by the reviewer. The UQCSbot on the main UQCS Discord server will now have your changes!
Clone this wiki locally