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.