Contributing¶

Development setup¶

Clone the repository and install all dependency groups (including dev and docs):

git clone https://codeberg.org/MarvinsMastodonTools/taibai.git
cd taibai
uv sync --all-groups
source .venv/bin/activate

Running checks¶

The project enforces five quality gates. Every change must pass all five before it is considered complete.

Format¶

ruff format .

Lint¶

ruff check . --fix

Type check¶

ty check .

Complexity¶

complexipy .

No function may exceed the configured complexity threshold.

Tests¶

nox -s pytest

Run the full CI suite at once:

nox

Test-driven development¶

taibai uses red/green TDD:

Write a failing test that captures the intended behaviour.
Make the minimal code change to make it pass.
Refactor as needed, keeping tests green.

Every new feature or bug fix must be accompanied by tests. Tests live in tests/ and use pytest-httpx to mock HTTP calls — no real network requests are made in the test suite.

# Run tests only
nox -s pytest

# Run with coverage
pytest --cov=taibai --cov-report=term-missing

Commit style¶

Commits follow Conventional Commits with short Commitizen-style messages:

type(scope): description

Common types: feat, fix, refactor, docs, test, chore.

Always append the co-author trailer:

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Off-limits files¶

The following files are maintained exclusively by the project maintainer and must not be edited in contributions:

ruff.toml
noxfile.py
cliff.toml
CHANGELOG.md

Release process¶

Releases are cut by the maintainer using:

just release patch   # 0.2.0 → 0.2.1
just release minor   # 0.2.0 → 0.3.0
just release major   # 0.2.0 → 1.0.0

Do not manually edit CHANGELOG.md or the version field in pyproject.toml.