CONTRIBUTING#

Contributing#

Thank you for your interest in contributing to redis_func_cache! This document provides guidelines and information to help you contribute effectively to the project.

Code of Conduct#

By participating in this project, you are expected to uphold our Code of Conduct, which promotes a welcoming and inclusive environment for all contributors.

How to Contribute#

Reporting Bugs#

Before reporting a bug, please check the existing issues to see if it has been reported. If not, create a new issue with:

A clear and descriptive title
A detailed description of the problem
Steps to reproduce the issue
Expected vs. actual behavior
Your environment information (Python version, Redis version, OS, etc.)

Suggesting Enhancements#

We welcome feature requests and suggestions. To propose an enhancement:

Check existing issues to avoid duplicates
Create a new issue with a clear title and detailed description
Explain why this enhancement would be useful
If possible, provide examples of how the feature would be used

Code Contributions#

Development Setup#

Fork the repository

Clone your fork:

git clone https://github.com/your-username/redis_func_cache.git
cd redis_func_cache

initialize the development environment

python -m venv .venv
source .venv/bin/activate
pip install -e .[all] --group dev

Or if you are using uv:

uv sync --all-extras

A virtual environment is created at directory .venv. You can activate it by running source .venv/bin/activate or .venv/Scripts/activate on Windows.

Running Tests#

Before submitting changes, ensure all tests pass:

Code Style#

We use several tools to maintain code quality:

Ruff: For linting and formatting. Check https://docs.astral.sh/ruff/ for more details.
MyPy: For static type checking. Check https://mypy.readthedocs.io/en/stable/ for more details.
Pre-commit hooks: To automatically check code before committing. Check https://pre-commit.com/ for more details.

You should install them before making changes.

To run checks manually:

# Run all pre-commit checks
pre-commit run -a

# Run lint and format
ruff check --fix
ruff format

# Run static type checking
mypy

Making Changes#

Create a new branch for your feature or bugfix:
```
git checkout -b feature/your-feature-name
```
Make your changes, following the code style guidelines
Add tests for new functionality
Ensure all tests pass (you may run redis server on localhost:6379 before running tests):
```
pytest -xv --cov
```
If the changes are concerned with Redis cluster, it is recommended to run the tests against a Redis cluster by docker compose:
```
cd docker
docker compose up --abort-on-container-exit
```
If you have standalone Redis server(s) running, you can run the tests against it/them by setting the environment variables
- REDIS_URL: url for the single Redis server
- REDIS_CLUSTER_NODES: ":" split list of Redis cluster nodes
A .env file can be used to set the environment variables.
Commit your changes with a clear, descriptive commit message
Push to your fork and submit a pull request

Pull Request Guidelines#

When submitting a pull request:

Provide a clear title and description
Reference any related issues
Ensure your code follows the project’s style guidelines
Include tests for new functionality
Update documentation as needed
Keep pull requests focused on a single feature or bugfix

Documentation#

Improvements to documentation are always welcome. This includes:

Updates to README.md
Docstring improvements
Examples and tutorials
Comments in code

Development Practices#

Lua Scripts#

This project uses Redis Lua scripts for atomic operations. When modifying Lua scripts:

Ensure scripts remain atomic and efficient
Test with various Redis versions
Keep scripts readable and well-commented
Follow existing patterns in the codebase

Testing#

We maintain high test coverage and follow these practices:

Write unit tests for new functionality
Test both synchronous and asynchronous code paths
Include edge cases and error conditions
Test with different cache policies
Use appropriate mocking when needed

Versioning#

We follow PEP 440.

Getting Help#

If you need help with your contribution:

Check the documentation and existing issues
Join our community discussions
Contact the maintainers directly

License#

By contributing to redis_func_cache, you agree that your contributions will be licensed under what described in the LICENSE.md file.

CONTRIBUTING

Contents