matchy/README.md

Matchy

Matchy matches matchees.

Matchy is a Discord bot that groups up users for fun and vibes. Matchy can be installed on your server by clicking here.

Commands

Matchy is mostly managed with commands in server channels. These are all listed below.

User commands

/join and /leave

Allows users to sign up and leave the group matching in the channel the command is used.

/pause [days: int(7)]

Allows users to pause their matching in a channel for a given number of days. Users can use /join to re-join before the end of that time.

/list

List the current matchees in the channel as well as any current scheduled match runs.

Matcher commands

Only usable by users with the matcher scope.

/match [group_min: int(3)]

Matches groups of users in a channel and offers a button to pose those groups to the channel to users with matcher auth scope. Tracks historical matches and attempts to match users to make new connections with people with divergent roles, in an attempt to maximise diversity.

/schedule [group_min: int(3)] [weekday: int(0)] [hour: int(9)] [cancel: bool(False)]

Allows a matcher to set a weekly schedule for matches in the channel, cancel can be used to remove a scheduled run

Admin commands

Only usable by users with the owner scope. Only usable in a DM with the bot user.

$sync and $close

Syncs bot commands or closes down the bot.

$grant [user: int]

Grant a given user the matcher scope to allow them to use /match and /schedule.

Development

Current development is on Linux, though running on Mac or Windows should work fine.

Dependencies

• python3 - Obviously, ideally 3.11
• venv - Used for the python virtual env, specs in requirements.txt

Getting Started

git clone git@github.com:mdiluz/matchy.git
cd matchy
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

VSCode can then be configured to use this new .venv and is the recommended way to develop.

Tests

Python tests are written to use pytest and cover most internal functionality. Tests can be run in the same way as in the Github Actions with scripts/test.py, which lints all python code and runs any tests with pytest.

Coverage

A helper script scripts/test-cov.py is available to generate a html view on current code coverage.

Hosting

Config

Matchy is configured by a required config.json file that takes this format:

{
    "version" : 1,
    "token" : "<<github bot token>>",

    "match" : {
        "score_factors": {
            "repeat_role" : 4,
            "repeat_match" : 8,
            "extra_member" : 32,
            "upper_threshold" : 64
        }
    }
}

Only token and version are required. To generate bot token for development see this discord.py guide.

See py/config.py for explanations for any extra settings here.

Running

It is recommended to only ever run the release branch in production, as this branch has passed the tests.

Running the bot can be as simple as python3 scripts/matchy.py, but a scripts/run.py script is provided to update to the latest release, install any new pip dependencies and run the bot.

The following command can be used to execute run.py on a loop, allowing the bot to be updated with a simple $close command from an owner user, but will still exit the loop if the bot throws a fatal error.

while ./scripts/run.py; end

State

State is stored locally in a state.json file. This will be created by the bot. This stores historical information on users, maching schedules, user auth scopes and more. See py/state.py for schema information if you need to inspect it.

TODO

• Implement better tests to the discordy parts of the codebase
• Implement a .json file upgrade test
• Track if matches were successful
• Improve the weirdo