teilchensammler/README.md

# Teilchensammler: Collect parts in a list

## Badges

[![status-badge](https://ci.c-base.org/api/badges/9/status.svg)](https://ci.c-base.org/repos/9)
[![Tested with Hypothesis](./docs/hypothesis-tested-brightgreen.svg)](https://hypothesis.readthedocs.io/)

## Development

This project makes use of [direnv] and [just].

[direnv] is used to set up environment variables and activate the virtualenv. I
recommend installing it and integrate it into your favourite shell. It works
well with fish shell.

[just] is used as a task runner.

[woodpecker-cli] is used to lint `.woodpecker/workflow.yaml`. It is available
from [homebrew].

[pytest] is the test runner. Invoke it using `just test` (any arguments will be
passed through to pytest).

### Getting started

Have Python >= 3.12 installed. I recommend [pyenv] (which in turn is easily
installed by [homebrew]).

Set up PostgreSQL, a role and a schema. I have it on localhost, using the
project name for role and schema name, and password. See `.env.test` for
providing connection information.

Clone the repo. `cd` into the project directory. ([direnv] should activate the
virtualenv.) Run `python -m pip install -U pip` to upgrade pip. Then `python -m
pip install -r requirements/dev.txt`.

Launch the dev server: `just serve` (or `python -m django runserver` when you
don't have just).

### Making changes

Change code, settings, templates, dependencies as you see fit. Run `just lint`
repeatedly. Don't forget migrations. Commit often.

### Using the App

`just serve` and open
[localhost:8000/collector](http://localhost:8000/collector/) in your browser.

## Dependency management

This project uses [pip-compile-multi] for hard-pinning dependencies versions.
Please see its documentation for usage instructions. In short,
`requirements/base.in` contains the list of direct requirements with occasional
version constraints (like `Django<2`) and `requirements/base.txt` is
automatically generated from it by adding recursive tree of dependencies with
fixed versions. The same goes for `test` and `dev`.

To upgrade dependency versions, run `just deps` (or `pip-compile-multi --uv`).
And to install those packages run `just sync`. To run both of those:

```shell
just deps sync
# OR
just fd
# OR
just freshdeps
```

To add a new dependency without upgrade, add it to the appropriate .in file and
run `pip-compile-multi --no-upgrade` (no [just] recipe yet).

### Installing dependencies

For installation of dependencies always use `requirement/*.txt` files.

For example, the command `pip install -U -r requirements/dev.txt` will install
testing requirements and development tools.

A useful command is `pip-sync requirements/dev.txt`, it uninstalls packages
from your virtualenv that aren't explicitly specified as dependencies.

[pip-compile-multi]: https://pypi.org/project/pip-compile-multi/
[direnv]: https://direnv.net/
[just]: https://just.systems/
[pyenv]: https://github.com/pyenv/pyenv
[homebrew]: https://brew.sh/
[pytest]: https://pytest.org/