diff --git a/.agents/project.md b/.agents/project.md index 165cfda..e126214 100644 --- a/.agents/project.md +++ b/.agents/project.md @@ -1,45 +1,49 @@ # Project profile - - ## About -- What this repository is, in one sentence: -- Who uses it: -- Language, version and main frameworks: -- Where the documentation lives: +- What this repository is: `redis-client-kit`, a Python library that builds redis-py clients, async and sync, for a standalone Redis or a Redis Cluster, with health checks, retries and graceful shutdown. It is published on PyPI. +- Who uses it: services that connect to Redis through redis-py. +- Language, version and main frameworks: Python 3.10 and newer. Its one runtime dependency is redis-py (`redis>=4.5.0,<9.0.0`). The optional extras are `settings` (Pydantic, pydantic-settings), `metrics` (prometheus-client), `providers` (Dishka) and `all`. Each lives in its own subpackage: `redis_client_kit/settings/`, `metrics/` and `providers/`. +- Where the documentation lives: https://bedrock-python.github.io/redis-client-kit/, built with Zensical from `docs/` (`zensical.toml`); the API reference is generated by mkdocstrings. `docs/agents.md` is the one-page reference for coding assistants. ## Commands | Task | Command | |---|---| -| Install dependencies | | -| Format | | -| Lint and type-check | | -| Test | | -| Run locally | | -| Stop the local run | | +| Install dependencies | `uv sync --all-extras --group dev` (`make install`). Without `--all-extras`, the test modules in `tests/unit/settings/`, `tests/unit/metrics/` and `tests/unit/providers/` fail at collection. | +| Format | `make fmt`: `uv run ruff format .`, then `uv run ruff check --fix .` | +| Lint and type-check | `make check`: `uv run ruff check .`, `uv run ruff format --check .`, `uv run mypy redis_client_kit` | +| Test | `make test-unit` (`uv run pytest -m unit`) needs no Docker. `make test-integration` (`uv run pytest -m integration`) needs Docker; without it those tests are skipped. `make test` runs both with `--cov-fail-under=90`. CI runs `uv run pytest -m unit` on Python 3.11, 3.12 and 3.13 and `uv run pytest -m integration` once, both without coverage. | +| Run locally | A library: nothing to run. The docs: `make docs-serve`. | +| Stop the local run | Ctrl+C in the terminal of `make docs-serve`. | ## Conventions -- Default branch: -- Issue tracker, and how commits and pull requests refer to an issue (for example `#123` or `ACME-123`): -- Branch names (for example `fix/123-short-description`): -- Commit messages (for example Conventional Commits): -- Language of pull request titles and descriptions: -- Where specs and design notes go: +- Default branch: `master`. The pre-commit hook `no-commit-to-branch` refuses commits to it. The ruleset `master-rules` takes changes only through a pull request whose `All checks passed` check is green. +- Issue tracker: GitHub Issues of this repository; refer to an issue as `#123`. +- Branch names: `/`, such as `feat/my-feature` (CONTRIBUTING.md). +- Commit messages: Conventional Commits, enforced by the `conventional-pre-commit` hook (`uv run pre-commit install --hook-type commit-msg`). Pull requests are squash-merged, and release-please reads the squash title, so a pull request's title is a Conventional Commit too. +- Language of pull request titles and descriptions: English. +- Where specs and design notes go: in the pull request description; the repository has no place for them. ## Boundaries -- Paths agents must not edit (generated code, vendored code, applied migrations): -- Systems and data agents must never touch: +- `CHANGELOG.md` is generated by release-please: never edit it by hand, and never add an `## [Unreleased]` section, even though the pull request template still has a checkbox for one. `docs/changelog.md` is a git-ignored copy that the docs build makes. +- release-please bumps the version in three places: `redis_client_kit/__version__.py` (the line marked `# x-release-please-version`), the fallback `__version__` in `redis_client_kit/__init__.py`, and `.release-please-manifest.json`. Never change them by hand. +- `docs/agents.md` is part of the public API: it changes in the same pull request as the API (CONTRIBUTING.md, "The agents page"). +- Files from the engineering-assets hub (`AGENTS.md` explains how it works) include: + - the copy-page files: `docs/assets/javascripts/copy-page.js`, `docs/assets/stylesheets/copy-page.css`, `overrides/main.html`, `scripts/emit_markdown.py`; + - `.github/workflows/docs.yml` and `.github/workflows/release-please.yml`; + - `.github/dependabot.yml`, `.editorconfig` and `CODE_OF_CONDUCT.md`. + + Change them in the hub; a change here makes the file this repository's own. +- Never publish to PyPI or create a release by hand: release-please creates the release, and `publish.yml` publishes it. ## Notes -Anything else an agent needs: the architecture in a few lines, known pitfalls, how to get test data. +- Releases: release-please opens its pull request with the workflow's own token, so CI does not start on it and the required `All checks passed` check never reports. Close and reopen the release pull request to run CI, then merge it. `publish.yml` runs after every Release Please run on `master`. It publishes to PyPI only when that commit has a `redis-client-kit-v` tag, which is the case once the release pull request is merged. Before 1.0, a breaking change bumps the minor version (`bump-minor-pre-major`). +- Tests: `tests/unit/conftest.py` and `tests/integration/conftest.py` add the marker `unit` or `integration` by directory (`--strict-markers`), so a new test goes in the right directory rather than taking a marker by hand. Integration tests start `redis:7-alpine` containers through testcontainers: a plain server, a primary full under `noeviction`, and a read-only replica. +- Python 3.10: CI's test matrix starts at 3.11, so only mypy and ruff check 3.10; both target it. +- `redis_client_kit/aio/` and `redis_client_kit/sync/` hold the same modules (`factory`, `instrumented`, `lifecycle`, `types`). A change to one side usually belongs on the other too, with tests in `tests/unit/aio/` and `tests/unit/sync/`. +- Code style (CONTRIBUTING.md): type hints on every function, tests included; Google-style docstrings on the public API only; lines up to 120 characters; double quotes; comments only for a non-obvious why.