Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
86 lines (63 loc) · 3.2 KB

CONTRIBUTING.md

File metadata and controls

86 lines (63 loc) · 3.2 KB
Raw

Contributing

Some short guidelines and points on contributing to Eos.

  • If you are a collaborator on the repo, create a branch directly and open your PR from it as normal.
  • If you are not a collaborator, fork the repo first, push your branch to your fork, then open a PR from your fork against master.
  • All changes must come via PR to master, this requires 1 approval.
  • I recommend sticking with feature/some-feature, bugfix/some-bug, chore/some-chore for branch names.

Local development with uv

The bot and API normally run via docker compose (see the README). For quicker iteration or debugging you can run them directly on your machine using uv, a fast Python package manager.

You can find the installation instruction for uv from here

The project is split into two workspaces namely:

  • eos-api: Source for the API backend made with flask.
  • eos-bot: Source for the bot implementation made with `discord.py

eos-api workspace is located under src/api/ and eos-bot workspace is located under src/bot/

Similarly, dependencies are split into two files: src/api/pyproject.toml and src/bot/pyproject.toml for the API and Bot source respectively. For the most part you won't be needing to manually edit these files.

Setting up uv environment

In your project run the following command to setup your environment-

uv sync

Activate your virtual environment for your respective OS-

For Linux / MacOS-

source .venv/bin/activate

For Windows-

.venv\Scripts\Activate.ps1  # For Windows PowerShell
.venv\Scripts\activate.bat  # For Windows Command Prompt

Managing dependencies via uv

To add any dependency you must first know under which workspace you want to add them to (eos-api or eos-bot). Once you know that, run the following command to add it to the particular workspace-

uv add --package <WORKSPACE-NAME> <LIBRARY-NAME>

For example if you want to add Django to the api workspace, the command will be-

uv add --package eos-api Django

To remove a dependency, you can do so like-

uv remove --package eos-bot Django

And then don't forget to re-sync your dependencies-

uv sync

pre-commit

We use pre-commit to run formatting, linting and security checks before each commit. The same checks run automatically in CI (.github/workflows/ci.yml) on every push and pull request to master.

Install the hooks once after cloning:

uv run --dev pre-commit install

After this, the checks run automatically whenever you git commit. Stage your changes with git add <file> first; if a hook modifies a file (e.g. ruff reformats it), re-stage it and commit again.

To run the checks manually against everything without committing:

uv run --dev pre-commit run --all-files

Or via Make-

make pre-commit

Note: running a service locally still depends on its surroundings — the bot needs the API reachable (FLASK_URL), and both need a populated src/.env. The easiest setup is to keep Postgres (and optionally the API) running in Docker while you run the service you're editing locally.