Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
130 lines (96 loc) · 3.65 KB

CONTRIBUTING.md

File metadata and controls

130 lines (96 loc) · 3.65 KB

Contributor guide

⚠️ Contribution at this point is not recommended, but isn't necessarily unwelcome. Please open an issue with the enhancement label with your proposed changes before beginning any work in earnest.

Virtual environment

It is all but required that you use a Python virtual environment for development. These instructions will assume that you are using pyenv, and have already installed and configured it on your system.

Create the environment

pyenv install 3.12  # if 3.12 isn't already installed
pyenv virtualenv 3.12 xthulu
pyenv activate xthulu

Install dependencies

In addition to the standard dependencies for the project, a set of developer-focused dependencies are included. Some of them are located in the dev optional dependencies bundle from the project's Python package, but others come from the node.js ecosystem. You should use a node version manager such as nvm in order to select the appropriate runtime version.

pip install -e .[dev]
nvm install
nvm use
npm ci

Development tools

husky

This project makes use of the husky git hooks system. The following applications are used to lint source code and check formatting:

  • ESLint - TypeScript linter/formatter
  • Prettier - Miscellaneous formatter
  • Ruff - Python linter/formatter

gitmoji

For conventional commit messages, this project has adopted the gitmoji standard. The prepare-commit-msg hook for crafting appropriately-categorized commit messages is handled by husky.

docker compose

In order to avoid the need to rebuild the service containers' base image each time you make changes to the source code, you can create an override configuration for the docker compose stack. This configuration will mount the live source code directory into the running containers so that restarting them should be sufficient to pick up any changes.

ℹ️ Userland scripts do not require a restart; a new session will import a fresh copy of the file(s). Changes to static web resources (HTML, CSS, Javascript, images) should be reflected immediately upon reloading the browser.

Copy the provided override configuration and adjust as necessary:

# in the docker/ directory
cp docker-compose.dev.yml docker-compose.override.yml

Testing

mypy

Type safety is enforced by the mypy package. You may run it individually, or you may use the example command in the pytest section to include type checking as part of test execution.

mypy xthulu

pytest

The project's chosen testing framework is pytest.

# run tests
pytest

# run tests, check types, and generate coverage report
pytest --mypy --cov .

Asynchronous test cases are supported via the pytest-asyncio plugin, but you must decorate your async test functions with @pytest.mark.asyncio for them to run successfully:

from asyncio import sleep
import pytest

@pytest.mark.asyncio
async def test_sleep():
    await sleep(1)

coverage

The coverage package is used to calculate test coverage after unit tests have been run. You may view the cached report at any time:

coverage report