Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
233 lines (166 loc) · 6.87 KB

CONTRIBUTING.md

File metadata and controls

233 lines (166 loc) · 6.87 KB
description Contributing your changes to Monty Python

Contributing

Thank you for your interest in contributing to Monty!

This document explains the contributing process in full. If your question isn't answered here, please open an issue

Issue Tracker

Reporting a bug

If you find a bug, please report it to the issue tracker with the details of what command you ran, whether or not the bot is in the server or if you have the bot installed to your user, and the guild ID. This will help us find the bug so we can fix it.

Requesting a new feature

If you're looking to submit a new feature, please create an issue on the issue tracker first, so the details can be discussed before submitting. If you have an idea for a new feature, but don't want to implement it yourself, PLEASE also create an issue! We love suggestions and new ideas, and want to ensure we're adding features that the community would actually use! Thank you!

Submitting a fix

Overview

The general workflow can be summarized as follows:

  1. Fork + clone the repository.
  2. Initialize the development environment: uv sync --all-groups && uv run prek install.
  3. Create a new branch.
  4. Commit your changes, update documentation if required.
  5. Push the branch to your fork, and submit a pull request!

But wait!

Before contributing, please make an issue for the specific fix or feature you are attempting to work on: we don't want you to work on a feature that someone else is already working on, so please check before you do! Small fixes, such as typos or logic bugs can be fixed without an issue, but this is best done on a case-by-case basis. If you're wondering, you can join the Discord Server to speak to the developer at any time.

Setting up a developer environment

Requirements

  • git
  • docker
    • docker compose
  • python 3.10
  • uv

Additionally, a postgresql database is required to develop Monty, but this is included in the developer docker-compose.yaml file.

If running the bot within docker, most of the following steps can be skipped as the environment is built within docker automatically. You'll still need to clone the repository and set up the git pre-commit hooks using prek.

Clone the repo

First step to getting started is to clone the repository:

git clone https://github.com/onerandomusername/monty-python
cd monty-python

Next, create a file named .env within the cloned repository.

A minimum viable contents (if using Docker) are as follows:

# contents of .env
BOT_TOKEN=...

# to change the default prefix from `-`
PREFIX=...

# optional, but necessary for anything using GitHub,
# required to enable the GitHub related code
GITHUB_TOKEN=...

Installing dependencies

TLDR:

uv sync --all-groups
uv run prek install

If you don't already have uv installed, check the uv documentation, or use a tool like pipx or uvx.

Make sure you run prek install, as it will integrate with git and lint every commit before committing, limiting the amount of fixes needing to be made in the review process.

Some fixes aren't automatic or done with prek, so take a look at Running CI locally

Create a Discord Bot

Go to the Discord Developer Portal and click on the "Create Application" button.

Follow the steps through and save the developer token. It needs to go in the .env created earlier.

You'll also need to connect this bot to at least one server you have access to.

Warning

Monty Python requires the message content intent and won't start if that intent is disabled. Be sure to enable it when configuring the bot.

Run a development instance

From this point, I suggest running two separate docker compose commands. The first one to run is docker compose up --detach postgres redis which starts the necessary dependent services. If contributing to the eval command, or global source, then snekbox is also required. The detach flag starts these services but does not watch them.

Running outside of Docker

For debugging, I personally run Monty outside of docker, but run the dependent services within docker. For this to be done, the following configuration is required in the .env file:

# within .env
BOT_TOKEN=... # token from earlier
# REQUIRED
DB_BIND='postgresql+asyncpg://monty:monty@localhost:5432/monty'
# to run database migrations/set up the bot for the first time
DB_RUN_MIGRATIONS=true

# optional, for -eval and global source development
SNEKBOX_URL='http://localhost:8060/'

# the redis connection bind if docker compose is running redis
REDIS_URI='redis://default@localhost:6379'
# optional: to only require postgres
USE_FAKEREDIS=true

Running in Docker

If the other services in Docker are already running, simply running the following should start the bot.

docker compose up monty

Monty should now be running! There's now a few other configuration things to do to finish initialising the database. See the bot only commands.

Running CI locally

As a public bot, Monty Python has continuous integration through GitHub actions and other developer tools to ensure that Monty is held to strict quality standards (as time progresses)!

To run the CI equivalent locally, we use nox as our runner.

uv run nox

With no arguments, this command will run all of the sessions and fixes that we run in CI.

If any changes are made, the results should be commited along with the rest of your code.

Commands and Autodoc

To document the procedures and methods on Monty, there is a custom script which serves to update two files listing the prefix and application commands that are available on Monty. These files are still in beta, and should not be relied at this moment for anything other than contributing documentation.

Running the autodoc session should automatically update these files, if there were any changes.

uv run nox -s autodoc

Building the documentation

To preview the documentation with an automatic reloading server, use the following command:

uv run nox -s docs

Alternatively you can run mkdocs directly once dev dependencies are installed:

uv run mkdocs serve

The dev server runs on http://127.0.0.1:8000 by default. Use mkdocs build to produce the static site into site/.

If you modified any documentation pages, including the CONTRIBUTING.md document or the README.md, make sure you run mdformat.

uv run nox -s mdformat