Development¶

Typed Settings uses:

uv for packaging and virtual env management
Hatch(ling) as build backend
nox as task manager, e.g. to run the linters and tests against a matrix of different dependency and Python versions. Nox is similar to tox but uses Python to describe all tasks.
pre-commit to lint the code you’re going to commit.

uv and pre-commit need to be installed globally via your favorite package manager. uv will handle everything else.

Setting up a Development Environment¶

Clone the project and change into its directory:

$ git clone git@gitlab.com:sscherfke/typed-settings.git
$ cd typed-settings

Create a virtual environment and install all development dependencies:
```
$ uv sync
$ source .venv/bin/activate
```
Note

If you don’t like activating venvs, prepend uv run to all invocations of nox, pytest or other tools, e.g.: uv run nox or uv run pytest.
Install the pre-commit hooks:
```
$ pre-commit install --install-hooks
```

Done. :-)

Linting¶

Typed Settings uses ruff and mypy for linting. You can run these tools directly but it’s easier to use nox:

(.venv)$ nox -e lint mypy

Ruff is also used for code formatting and auto-fixing linting issues. You should use nox to run it:

(.venv)$ nox -e fix

Pre-commit also runs all linters and formatters with all changed files every time you want to commit something.

Testing¶

You run the tests with pytest. It is configured to also run doctests in src/ and docs/ and to test the examples in that directory, so do not only run it on tests/.

(.venv)$ pytest

You can also use nox to run tests for all supported Python versions at the same time. This will also calculate the combined test coverage and run the linters.

(.venv)$ nox

Docs¶

Sphinx is used to build the documentation. The documentation is formatted with Markdown using MyST (with the exception of the API docs, which are formatted with ReStructuredText). There’s a Makefile that you can invoke to build the documentation:

(.venv)$ make -C docs html
(.venv)$ make -C docs clean html  # Clean rebuild
(.venv)$ open docs/_build/html/index.html  # Use "xdg-open" on Linux

You can also use nox:

(.venv)$ nox -e docs  # Just build changed pages
(.venv)$ nox -e docs -- clean  # Clean build
(.venv)$ nox -e docs -- open  # open docs in browser
(.venv)$ nox -e docs -- clean open  # Clean build and open

Commits¶

When you commit something, take your time to write a precise, meaningful commit message. In short:

Use the imperative: Fix issue with XY.
If your change is non-trivial, describe why your change was needed and how it works. Separate this from the title with an empty line.
Add references to issues, e.g. See: #123 or Fixes: #123.

When any of the linters run by Pre-commit finds an issue or if a formatter changes a file, the commit is aborted. In that case, you need to review the changes, add the files and try again:

(.venv)$ git status
(.venv)$ git diff
(.venv)$ git add src/typed_settings/...

Releasing New Versions¶

Releases are created and uploaded by the CI/CD pipeline. The release steps are only executed in tag pipelines.

To prepare a release:

Add missing entries to the CHANGELOG.md. Use an emoji for each line. The changelog contains a legend at the bottom where you can look-up the proper emoji.
Add the current date as release date to the latest (unreleased) section in CHANGELOG.md.
Commit using the message Bump version from a.b.c to x.y.z.
Push the changes and make sure the CI pipeline succeeds.
Check the results on the testing PyPI.
Create an annotated tag: git tag -am 'Release x.y.z' x.y.z.
Push the tag: git push origin x.y.z.
Approve the upload step in the CI/CD pipeline. This will then create a release on PyPI.
Check the release on PyPI.
Toot something about it using #TypedSettings. :-)