Development¶

Typed Settings uses Hatch as build tool. However, you can set-up your local development environment in whichever way you like.

It uses 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.

It also uses pre-commit to lint the code you’re going to commit.

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 in your preferred ways, for example:
- Using Hatch:
```
$ hatch shell
```
  This not only creates and activates an environment but also installs/updates all development dependencies and pre-commit.
- Using uv:
```
$ uv venv
$ source .venv/bin/activate
```
- Using venv:
```
$ python -m venv .venv
$ source .venv/bin/activate
```

If you did not use Hatch, install all development requirements and Typed Settings itself in development mode:

(typed-settings)$ uv pip install -e .[dev]
(typed-settings)$ # or, if you don't use "uv":
(typed-settings)$ pip install -e .[dev]
(typed-settings)$
(typed-settings)$ pre-commit install --install-hooks

Linting¶

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

(typed-settings)$ nox -e lint mypy

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

(typed-settings)$ 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/.

(typed-settings)$ 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.

(typed-settings)$ 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:

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

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:

(typed-settings)$ git status
(typed-settings)$ git diff
(typed-settings)$ 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:

Update 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.
Update the version in pyproject.toml.
Commit using the message Bump version from a.b.c to x.y.z.
Create an annotated tag: git tag -am 'Release x.y.z' x.y.z.
Push everything: git push --atomic origin main x.y.z.
The CI/CD pipeline automatically creates a release on the testing PyPI. Check if everything is okay.
Manually trigger the final release step.