Contributing

Bug reports, questions and pull requests are welcome. Please open an issue before starting on a larger change, so that we can agree on its design first.

Development setup

$ git clone https://github.com/smarter-sh/cache-results.git
$ cd cache-results
$ make init

make init creates the repository’s own virtual environment, venv/, from the pinned requirements/local.txt, installs the package in editable mode, and installs the pre-commit hooks. make alone lists every command.

$ make test             # the tests, against the local-memory cache
$ make test-redis       # the tests, against Redis (REDIS_URL)
$ make coverage         # with a coverage report: at least 95%
$ make typecheck        # mypy, with django-stubs
$ make lint             # the pre-commit hooks, on every file
$ make sphinx-build     # these docs, with warnings as errors

Pull requests

Fork the repository, and branch from main.
Make your change with its tests. make coverage must stay at 95% or more, and both make test and make test-redis must pass. CI checks all of this, on every supported Python and Django version.
Update the docs and docstrings for anything a user can see.
Write conventional commits, e.g. fix(keys): sort frozensets of tuples. Releases are versioned from them: fix makes a patch release, feat a minor one.
Open a pull request that says what changed and why, and links its issue.

A few rules keep cached results safe and readable. They are explained in the Architectural Decision Records:

The package depends only on Django and asgiref. Project-specific behavior belongs in a project’s own hooks, named by the CACHE_RESULTS setting.
Arguments are never keyed by str(), and results and secrets are never logged.
A change to the key format, or to the value stored for None, makes every cached entry unreadable, so it needs a major release.

Code of conduct

Everyone who takes part is expected to follow the code of conduct. Governance of the Smarter projects is described in smarter-sh/community.