Skip to content

Contributing#

Environment Setup#

pipx

This documentaion uses pipx to install and manage non-project command line tools like hatch and pre-commit. If you don't already have pipx installed, make sure to see their documentation. If you prefer not to use pipx, you can use pip instead.

  1. Install hatch

    pipx install hatch
    

    pre-commit

    Hatch will attempt to set up pre-commit hooks for you using pre-commit. If you don't already, make sure to install pre-commit as well: pipx install pre-commit

  2. Build the Virtual Environment

    hatch env create
    
  3. If you need to, you can link hatch's virtual environment to your IDE. It's located in the .venv directory at the root of the project.

  4. Activate the Virtual Environment

    hatch shell
    

Using Hatch#

Hatch Cheat Sheet#

Command Description Command Notes
Run Tests hatch run cov Runs tests with pytest and coverage
Run Formatting hatch run lint:fmt Runs black and ruff code formatters
Run Linting hatch run lint:all Runs ruff and mypy linters / type checkers
Generate OpenAPI Spec and Clients hatch run gen:all
Serve the Documentation hatch run docs:serve Serve the documentation using MkDocs
Run the Application Locally hatch run app:serve Serve the app with uvicorn using a SQLite Database
Run the Application in Docker hatch run app:container Serve the app using a docker compose stack
Run the pre-commit Hooks hatch run lint:precommit Runs the pre-commit hooks on all files

Hatch Explanation#

Hatch is a Python package manager. Its most basic use is as a standardized build-system. However, hatch also has some extra features which this project takes advantage of. These features include virtual environment management and the organization of common scripts like linting and testing. All the operations in hatch take place in one of its managed virtual environments.

Hatch has a variety of environments, to see them simply ask hatch:

hatch env show
                            Standalone                            
โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”“
โ”ƒ Name    โ”ƒ Type        โ”ƒ Dependencies         โ”ƒ Scripts         โ”ƒ
โ”กโ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ฉ
โ”‚ default โ”‚ pip-compile โ”‚                      โ”‚ cov             โ”‚
โ”‚         โ”‚             โ”‚                      โ”‚ test            โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚ app     โ”‚ pip-compile โ”‚                      โ”‚ container       โ”‚
โ”‚         โ”‚             โ”‚                      โ”‚ container-reset โ”‚
โ”‚         โ”‚             โ”‚                      โ”‚ cov             โ”‚
โ”‚         โ”‚             โ”‚                      โ”‚ migrate         โ”‚
โ”‚         โ”‚             โ”‚                      โ”‚ reset           โ”‚
โ”‚         โ”‚             โ”‚                      โ”‚ serve           โ”‚
โ”‚         โ”‚             โ”‚                      โ”‚ test            โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚ docs    โ”‚ pip-compile โ”‚ markdown-exec        โ”‚ build           โ”‚
โ”‚         โ”‚             โ”‚ mkdocs               โ”‚ gh-deploy       โ”‚
โ”‚         โ”‚             โ”‚ mkdocs-autorefs      โ”‚ serve           โ”‚
โ”‚         โ”‚             โ”‚ mkdocs-gen-files     โ”‚                 โ”‚
โ”‚         โ”‚             โ”‚ mkdocs-literate-nav  โ”‚                 โ”‚
โ”‚         โ”‚             โ”‚ mkdocs-material      โ”‚                 โ”‚
โ”‚         โ”‚             โ”‚ mkdocs-section-index โ”‚                 โ”‚
โ”‚         โ”‚             โ”‚ mkdocstrings         โ”‚                 โ”‚
โ”‚         โ”‚             โ”‚ mkdocstrings-python  โ”‚                 โ”‚
โ”‚         โ”‚             โ”‚ pymdown-extensions   โ”‚                 โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚ gen     โ”‚ pip-compile โ”‚                      โ”‚ all             โ”‚
โ”‚         โ”‚             โ”‚                      โ”‚ cov             โ”‚
โ”‚         โ”‚             โ”‚                      โ”‚ docs            โ”‚
โ”‚         โ”‚             โ”‚                      โ”‚ openapi         โ”‚
โ”‚         โ”‚             โ”‚                      โ”‚ release         โ”‚
โ”‚         โ”‚             โ”‚                      โ”‚ test            โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚ lint    โ”‚ pip-compile โ”‚ mypy>=1.6.1          โ”‚ all             โ”‚
โ”‚         โ”‚             โ”‚ ruff~=0.1.7          โ”‚ fmt             โ”‚
โ”‚         โ”‚             โ”‚                      โ”‚ precommit       โ”‚
โ”‚         โ”‚             โ”‚                      โ”‚ style           โ”‚
โ”‚         โ”‚             โ”‚                      โ”‚ typing          โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚ test    โ”‚ pip-compile โ”‚ pytest               โ”‚ cov             โ”‚
โ”‚         โ”‚             โ”‚ pytest-cov           โ”‚ test            โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                          Matrices                          
โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”“
โ”ƒ Name โ”ƒ Type        โ”ƒ Envs       โ”ƒ Dependencies โ”ƒ Scripts โ”ƒ
โ”กโ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ฉ
โ”‚ all  โ”‚ pip-compile โ”‚ all.py3.8  โ”‚ pytest       โ”‚ cov     โ”‚
โ”‚      โ”‚             โ”‚ all.py3.9  โ”‚ pytest-cov   โ”‚ migrate โ”‚
โ”‚      โ”‚             โ”‚ all.py3.10 โ”‚              โ”‚ test    โ”‚
โ”‚      โ”‚             โ”‚ all.py3.11 โ”‚              โ”‚         โ”‚
โ”‚      โ”‚             โ”‚ all.py3.12 โ”‚              โ”‚         โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

That above command will tell you that there are six environments that you can use:

  • default
  • app
  • docs
  • gen
  • lint
  • test

Each of these environments has a set of commands that you can run. To see the commands for a specific environment, run:

hatch env show default
            Standalone             
โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”“
โ”ƒ Name    โ”ƒ Type        โ”ƒ Scripts โ”ƒ
โ”กโ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ฉ
โ”‚ default โ”‚ pip-compile โ”‚ cov     โ”‚
โ”‚         โ”‚             โ”‚ test    โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Here we can see that the default environment has the following commands:

  • cov
  • test

The one that we're interested in is cov, which will run the tests for the project.

hatch run cov

Since cov is in the default environment, we can run it without specifying the environment. However, to run the serve command in the docs environment, we need to specify the environment:

hatch run docs:serve

You can see what scripts are available using the env show command

hatch env show docs
                       Standalone                        
โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ณโ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”“
โ”ƒ Name โ”ƒ Type        โ”ƒ Dependencies         โ”ƒ Scripts   โ”ƒ
โ”กโ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ•‡โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ฉ
โ”‚ docs โ”‚ pip-compile โ”‚ markdown-exec        โ”‚ build     โ”‚
โ”‚      โ”‚             โ”‚ mkdocs               โ”‚ gh-deploy โ”‚
โ”‚      โ”‚             โ”‚ mkdocs-autorefs      โ”‚ serve     โ”‚
โ”‚      โ”‚             โ”‚ mkdocs-gen-files     โ”‚           โ”‚
โ”‚      โ”‚             โ”‚ mkdocs-literate-nav  โ”‚           โ”‚
โ”‚      โ”‚             โ”‚ mkdocs-material      โ”‚           โ”‚
โ”‚      โ”‚             โ”‚ mkdocs-section-index โ”‚           โ”‚
โ”‚      โ”‚             โ”‚ mkdocstrings         โ”‚           โ”‚
โ”‚      โ”‚             โ”‚ mkdocstrings-python  โ”‚           โ”‚
โ”‚      โ”‚             โ”‚ pymdown-extensions   โ”‚           โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Committing Code#

This project uses pre-commit to run a set of checks on the code before it is committed. The pre-commit hooks are installed by hatch automatically when you run it for the first time.

This project uses semantic-versioning standards, managed by semantic-release. Releases for this project are handled entirely by CI/CD via pull requests being merged into the main branch. Contributions follow the gitmoji standards with conventional commits.

While you can denote other changes on your commit messages with gitmoji, the following commit message emoji prefixes are the only ones to trigger new releases:

Emoji Shortcode Description Semver
๐Ÿ’ฅ :boom: Introduce breaking changes. Major
โœจ :sparkles: Introduce new features. Minor
๐Ÿ› :bug: Fix a bug. Patch
๐Ÿš‘ :ambulance: Critical hotfix. Patch
๐Ÿ”’ :lock: Fix security issues. Patch

Most features can be squash merged into a single commit on a pull-request. When merging multiple commits, they will be summarized into a single release.

If you're working on a new feature, your commit message might look like:

โœจ New Feature Description

Bug fix commits would look like this:

๐Ÿ› Bug Fix Description

If you're working on a feature that introduces breaking changes, your commit message might look like:

๐Ÿ’ฅ Breaking Change Description

Other commits that don't trigger a release might look like this:

๐Ÿ“ Documentation Update Description
๐Ÿ‘ท CI/CD Update Description
๐Ÿงช Testing Changes Description
๐Ÿšš Moving/Renaming Description
โฌ†๏ธ Dependency Upgrade Description

Pre-Releases#

semantic-release supports pre-releases. To trigger a pre-release, you would merge your pull request into an alpha or beta branch.

Specific Release Versions#

In some cases you need more advanced control around what kind of release you need to create. If you need to release a specific version, you can do so by creating a new branch with the version number as the branch name. For example, if the current version is 2.3.2, but you need to release a fix as 1.2.5, you would create a branch named 1.2.x and merge your changes into that branch.

See the semantic-release documentation for more information about branch based releases and other advanced release cases.