Contributing¶

Development setup¶

This project uses Poetry for dependency management and packaging.

Create a virtual environment, install Poetry into it, then install the project dependencies:

git clone https://gitlab.com/velocipy/velocipy.git
cd velocipy
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install poetry
poetry install --extras all

After poetry install, all CLI tools are available directly in the active virtual environment. Run them natively — no poetry run prefix needed.

poetry install installs the dev dependency group, which includes the test, lint, and docs groups. The --extras all flag also installs every runtime feature extra so the full test suite and type checks can run.

To install only what is needed to run tests (without lint/docs tools):

poetry install --with test --extras all

Git hooks¶

This project uses prek to run git hooks. After installing the dev dependencies, install the hooks once:

prek install

The hooks run ruff (lint + format), mypy, and pre-commit-update automatically on commits. To run them manually against all files:

prek run --all-files

Running tests¶

pytest -q

Linting and type checking¶

ruff check velocipy tests examples
ruff format --check velocipy tests examples
mypy velocipy tests examples

Changelog¶

If your change is user-facing, add a concise entry to docs/changelog.md under the ## Unreleased heading. Entries must be grouped in subsections so users can quickly see what kind of impact a release has.

Use these subsections, in this order:

Subsection	Use for
`### Breaking changes`	Changes that require users to update their code or configuration. Always explain the migration path.
`### Security`	Fixes for vulnerabilities, hardening, or behavior that closes security gaps.
`### Added`	New features, public APIs, modules, or options.
`### Changed`	Improvements to existing behavior, defaults, docs, or internals that are visible to users.
`### Deprecated`	Features still present but scheduled for removal. Include the planned removal version if known.
`### Removed`	Deleted features, modules, or options.
`### Fixed`	Bug fixes, including fixes for crashes, incorrect behavior, or regressions.

Writing style¶

Write from the user's perspective, not the implementer's.
Start with a verb in the past participle (Added, Fixed, Changed) or present imperative (Add, Fix, Change) and keep the same voice within a release.
Be specific but concise. Mention the affected public API when relevant.
One change per bullet. Do not bundle unrelated fixes into one line.
If an issue or merge request exists, add its reference at the end of the line when it adds meaningful context.

Example¶

## Unreleased

### Breaking changes

- Removed the old `velocipy.limiter.storage` module. Import `MemoryStorage` and
  `RedisStorage` from `velocipy.storage` instead.

### Security

- Reject whitespace-only API key values as missing credentials.

### Added

- Added server-side route response caching via `Cache` and `CachePolicy`.

### Changed

- Rate limiter now shares the same `Storage` abstraction as the cache.

### Fixed

- Fixed cache lookup when `dependency_overrides` is active.

When a release is cut, replace ## Unreleased with the new version heading and add a fresh empty ## Unreleased section at the top.

Building docs¶

zensical build --strict
zensical serve