Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
180 lines (115 loc) · 4.8 KB

CONTRIBUTING.md

File metadata and controls

180 lines (115 loc) · 4.8 KB

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:

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

Code Contributions

Development Setup

  1. Fork the repository

  2. Clone your fork:

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

  3. 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:

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

  1. Create a new branch for your feature or bugfix:

    git checkout -b feature/your-feature-name

  2. Make your changes, following the code style guidelines

  3. Add tests for new functionality

  4. 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.

  5. Commit your changes with a clear, descriptive commit message

  6. Push to your fork and submit a pull request

Pull Request Guidelines

When submitting a pull request:

  1. Provide a clear title and description
  2. Reference any related issues
  3. Ensure your code follows the project's style guidelines
  4. Include tests for new functionality
  5. Update documentation as needed
  6. 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:

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

Testing

We maintain high test coverage and follow these practices:

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

Versioning

We follow PEP 440.

Getting Help

If you need help with your contribution:

  1. Check the documentation and existing issues
  2. Join our community discussions
  3. 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.