Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
168 lines (107 loc) · 6.11 KB

CONTRIBUTING.md

File metadata and controls

168 lines (107 loc) · 6.11 KB

Contributing

This bot is a Python based Discord bot built on top of the discord.py library.

It uses uv to manage dependencies. To install development dependencies use: uv sync. This will allow you to run PyTest and the included scripts.

You can install uv with the script brew:

brew install uv

Installing the application

Install in development mode via uv:

uv sync

Launch Dependencies

SpellBot requires a database to run properly. The connection string for the database you want to use must be stored in the environment variable DATABASE_URL.

You can start a local database via Docker by running:

docker run -i --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres:17

Using this locally will allow you to use the default value for DATABASE_URL without having to manually set it to anything.

For more details on managing the database, see our database documentation.

Running the application

Make sure that you have set up your environmental variables.

If you wish, you can use a .env file. Copy the .env.example file to get started.

When your environmental variables are set, run:

uv run spellbot --help

This will list some useful flags you can provide to run SpellBot. To get started developing, run:

uv run spellbot --dev

This will start SpellBot and reload it whenever the source code changes.

You may also want to use --mock-games and --disable-tasks for development purposes. Additionally you may want to start a seperate process for the API with uv run spellbot --dev --api so that you can test API changes locally as well.

To start everything in development mode just use:

make dev

Running tests

uv run pytest --cov --cov-report=html
open htmlcov/index.html

Frontend tests

The admin dashboard and public analytics pages each ship a large IIFE-scoped JavaScript file (src/spellbot/web/templates/dashboard.js, analytics.js). The pure (side-effect free) helpers from those files — date/bucket math, timezone conversion, HTML escaping, row rendering, etc. — live in companion *_pure.js files and are unit-tested with Vitest under Node.

At serve time, serve_dashboard_js / serve_analytics_js concatenate the *_pure.js file in front of the main *.js file, so the top-level function declarations in the pure file become globals visible to the IIFE in the browser. A trailing module.exports block in each *_pure.js is a no-op in the browser and lets Vitest import the same helpers under Node.

To install the JS dev dependencies and run the tests:

npm install
npm test

To get a coverage report restricted to the two *_pure.js files:

npx vitest run --coverage

When adding new browser logic, prefer putting any time/data transformation into the matching *_pure.js file (taking Date.now() / new Date() as an explicit argument so tests can pin time) and keep DOM, fetch, and Chart.js wiring in the main *.js file.

Formatting and linting

Codebase consistency is maintained by ruff.

uv run pytest -k codebase

Interactive Shell

An interactive shell using IPython can be started by running:

uv run python shell.py

From this shell you will be able to interact with the database using SpellBot models and code. The shell runs in async mode, so use await with database operations. For example:

$ uv run python shell.py

In [1]: (await DatabaseSession.execute(select(User))).scalars().all()
Out[1]: []

Release process

There's two methods for doing a release. You can use a script to handle everything for you automatically, or you can basically do every step in that script manually. Both methods are described below but I recommend the script.

Scripted

To do a release automatically there is a *NIX script available in the scripts directory to help. To use it you will need to have non-interactive uv publish enabled by running:

uv publish --token "YOUR-PYPI-TOKEN-GOES-HERE"

If you don't have one, you can create your PyPI token for this command by going to the PyPI settings for spellbot and clicking on the Create a token for spellbot button there. Of course you will have to be a collaborator for this project on PyPI to be able to do this. Contact spellbot@lexicalunit.com to be added to the project.

Once you have that set up, you can release a new version by running:

scripts/publish.sh <major | minor | patch>

You must select either major, minor, or patch as the release kind. Please follow semver for guidance on what kind of release to make. But basically:

  • Major: Breaking changes.
  • Minor: New features.
  • Patch: Bug fixes.

Manually

To release a new version of spellbot, use uv:

uv version --bump [major|minor|patch]
uv run pytest # verify that all tests pass
# edit the CHANGELOG.md file to promote all unreleased changes to the new version
uv build
git commit -am "Release vM.N.P"
uv publish # you will be prompted for your PyPI login credentials here
git tag 'vM.N.P'
git push --tags origin main

Note: The reason you should run pytest after running the uv version command is to ensure that all test still pass after the version is updated.

You can get the M.N.P version numbers from pyproject.toml after you've run the uv version command. On a *NIX shell you could also get it automatically like so:

grep "^version" < pyproject.toml | cut -d= -f2 | sed 's/"//g;s/ //g;s/^/v/;'

After publishing you can view the package at its pypi.org project page to see that everything looks good.