Skip to content
Back to top
View this page

# Contributing

Development of `sqlite-utils` takes place in the sqlite-utils GitHub repository.

All improvements to the software should start with an issue. Read How I build a feature for a detailed description of the recommended process for building bug fixes or enhancements.

## Obtaining the code

To work on this library locally, first checkout the code:

    git clone git@github.com:simonw/sqlite-utils
    cd sqlite-utils

Use `uv run` to run the development version of the tool:

    uv run sqlite-utils --help

## Running the tests

Use `uv run` to run the tests:

    uv run pytest

## Building the documentation

To build the documentation run this command:

    uv run make livehtml --directory docs

This will start a server on port 8000 that will serve the documentation and live-reload any time you make an edit to a `.rst` file.

The cog tool is used to maintain portions of the documentation. You can run it like so:

    uv run cog -r docs/*.rst

## Linting and formatting

`sqlite-utils` uses Black for code formatting, and flake8 and mypy for linting and type checking:

    uv run black .

Linting tools can be run like this:

    uv run flake8
    uv run mypy sqlite_utils

All three of these tools are run by our CI mechanism against every commit and pull request.

## Using Just

If you install Just you can use it to manage your local development environment.

To run all of the tests and linters:

    just

To run tests, or run a specific test module or test by name:

    just test # All tests
    just test tests/test_cli_memory.py # Just this module
    just test -k test_memory_no_detect_types # Just this test

To run just the linters:

    just lint

To apply Black to your code:

    just black

To update documentation using Cog:

    just cog

To run the live documentation server (this will run Cog first):

    just docs

And to list all available commands:

    just -l

## Release process

Releases are performed using tags. When a new release is published on GitHub, a GitHub Actions workflow will perform the following:

- Run the unit tests against all supported Python versions. If the tests pass…

- Build a wheel bundle of the underlying Python source code

- Push that new wheel up to PyPI: https://pypi.org/project/sqlite-utils/

To deploy new releases you will need to have push access to the GitHub repository.

`sqlite-utils` follows Semantic Versioning:

    major.minor.patch

We increment `major` for backwards-incompatible releases.

We increment `minor` for new features.

We increment `patch` for bugfix releass.

To release a new version, first create a commit that updates the version number in `pyproject.toml` and the the changelog with highlights of the new version. An example commit can be seen here:

    # Update changelog
    git commit -m " Release 3.29

    Refs #423, #458, #467, #469, #470, #471, #472, #475" -a
    git push

Referencing the issues that are part of the release in the commit message ensures the name of the release shows up on those issue pages, e.g. here.

You can generate the list of issue references for a specific release by copying and pasting text from the release notes or GitHub changes-since-last-release view into this Extract issue numbers from pasted text tool.

To create the tag for the release, create a new release on GitHub matching the new version number. You can convert the release notes to Markdown by copying and pasting the rendered HTML into this Paste to Markdown tool.