|
2 | 2 |
|
3 | 3 | ## Introduction
|
4 | 4 |
|
5 |
| -First off, thank you for considering contributions. We value community contributions! |
| 5 | +First off, thank you for considering contributions to RedisVL! We value community contributions and appreciate your interest in helping make this project better. |
6 | 6 |
|
7 |
| -## Contributions We Need |
| 7 | +## Types of Contributions We Need |
8 | 8 |
|
9 |
| -You may already know what you want to contribute \-- a fix for a bug you |
10 |
| -encountered, or a new feature your team wants to use. |
| 9 | +You may already know what you want to contribute -- a fix for a bug you encountered, or a new feature your team wants to use. |
11 | 10 |
|
12 |
| -If you don't know what to contribute, keep an open mind! Improving |
13 |
| -documentation, bug triaging, and writing tutorials are all examples of |
14 |
| -helpful contributions that mean less work for you. |
| 11 | +If you don't know what to contribute, keep an open mind! Here are some valuable ways to contribute: |
15 | 12 |
|
16 |
| -## Your First Contribution |
17 |
| - |
18 |
| -Unsure where to begin contributing? You can start by looking through some of our issues [listed here](https://github.com/redis/redis-vl-python/issues). |
| 13 | +- **Bug fixes**: Help us identify and resolve issues |
| 14 | +- **Feature development**: Add new functionality that benefits the community |
| 15 | +- **Documentation improvements**: Enhance clarity, add examples, or fix typos |
| 16 | +- **Bug triaging**: Help categorize and prioritize issues |
| 17 | +- **Writing tutorials**: Create guides that help others use RedisVL |
| 18 | +- **Testing**: Write tests or help improve test coverage |
19 | 19 |
|
20 | 20 | ## Getting Started
|
21 | 21 |
|
22 | 22 | Here's how to get started with your code contribution:
|
23 | 23 |
|
24 |
| -1. Create your own fork of this repo |
25 |
| -2. Set up your developer environment |
26 |
| -2. Apply the changes in your forked codebase / environment |
27 |
| -4. If you like the change and think the project could use it, send us a |
28 |
| - pull request. |
| 24 | +1. **Fork the repository**: Create your own fork of this repo |
| 25 | +2. **Set up your development environment**: Follow the setup instructions below |
| 26 | +3. **Make your changes**: Apply the changes in your forked codebase |
| 27 | +4. **Test your changes**: Ensure your changes work and don't break existing functionality |
| 28 | +5. **Submit a pull request**: If you like the change and think the project could use it, send us a pull request |
29 | 29 |
|
30 |
| -### Dev Environment |
31 |
| -RedisVL uses [Poetry](https://python-poetry.org/) for dependency management. |
| 30 | +## Development Environment Setup |
32 | 31 |
|
33 |
| -Follow the instructions to [install Poetry](https://python-poetry.org/docs/#installation). |
| 32 | +### Prerequisites |
34 | 33 |
|
35 |
| -Then install the required libraries: |
| 34 | +- **Python**: RedisVL supports Python 3.8 and above |
| 35 | +- **Docker**: Required for running Redis Stack and integration tests |
| 36 | +- **UV**: Modern Python package manager for fast dependency management |
36 | 37 |
|
37 |
| -```bash |
38 |
| -poetry install --all-extras |
39 |
| -``` |
| 38 | +### Installing UV |
40 | 39 |
|
41 |
| -### Optional Makefile |
| 40 | +RedisVL uses [UV](https://docs.astral.sh/uv/) for fast, modern Python dependency management. Choose your preferred installation method: |
42 | 41 |
|
43 |
| -If you use `make`, we've created shortcuts for running the commands in this document. |
| 42 | +#### Standalone Installer (Recommended) |
44 | 43 |
|
45 |
| -| Command | Description | |
46 |
| -|---------|-------------| |
47 |
| -| make install | Installs all dependencies using Poetry| |
48 |
| -| make redis-start | Starts Redis Stack in a Docker container on ports 6379 and 8001 | |
49 |
| -| make redis-stop | Stops the Redis Stack Docker container | |
50 |
| -| make format | Runs code formatting and import sorting | |
51 |
| -| make check-types | Runs mypy type checking | |
52 |
| -| make lint | Runs formatting, import sorting, and type checking | |
53 |
| -| make test | Runs tests, excluding those that require API keys and/or remote network calls| |
54 |
| -| make test-all | Runs all tests, including those that require API keys and/or remote network calls| |
55 |
| -| make test-notebooks | Runs all notebook tests| |
56 |
| -| make check | Runs all linting targets and a subset of tests | |
57 |
| -| make docs-build | Builds the documentation | |
58 |
| -| make docs-serve | Serves the documentation locally | |
59 |
| -| make clean | Removes all generated files (cache, coverage, build artifacts, etc.) | |
60 |
| - |
61 |
| -### Linting and Tests |
62 |
| - |
63 |
| -Check formatting, linting, and typing: |
| 44 | +**macOS and Linux:** |
64 | 45 | ```bash
|
65 |
| -poetry run format |
66 |
| -poetry run sort-imports |
67 |
| -poetry run check-mypy |
| 46 | +curl -LsSf https://astral.sh/uv/install.sh | sh |
68 | 47 | ```
|
69 | 48 |
|
70 |
| -#### TestContainers |
| 49 | +**Windows:** |
| 50 | +```powershell |
| 51 | +powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" |
| 52 | +``` |
71 | 53 |
|
72 |
| -RedisVL uses Testcontainers Python for integration tests. Testcontainers is an open-source framework for provisioning throwaway, on-demand containers for development and testing use cases. |
| 54 | +#### Alternative Installation Methods |
73 | 55 |
|
74 |
| -To run Testcontainers-based tests you need a local Docker installation such as: |
75 |
| -- [Docker Desktop](https://www.docker.com/products/docker-desktop/) |
76 |
| -- [Docker Engine on Linux](https://docs.docker.com/engine/install/) |
| 56 | +**Homebrew (macOS):** |
| 57 | +```bash |
| 58 | +brew install uv |
| 59 | +``` |
77 | 60 |
|
78 |
| -#### Running the Tests |
| 61 | +**pipx:** |
| 62 | +```bash |
| 63 | +pipx install uv |
| 64 | +``` |
79 | 65 |
|
80 |
| -Tests w/ external APIs: |
| 66 | +**pip:** |
81 | 67 | ```bash
|
82 |
| -poetry run test-verbose --run-api-tests |
| 68 | +pip install uv |
83 | 69 | ```
|
84 | 70 |
|
85 |
| -Tests w/out external APIs: |
| 71 | +For more installation options, see the [official UV installation guide](https://docs.astral.sh/uv/getting-started/installation/). |
| 72 | + |
| 73 | +### Project Setup |
| 74 | + |
| 75 | +Once UV is installed, set up the project dependencies: |
| 76 | + |
86 | 77 | ```bash
|
87 |
| -poetry run test-verbose |
| 78 | +# Install all dependencies including development and optional extras |
| 79 | +uv sync --all-extras |
88 | 80 | ```
|
89 | 81 |
|
90 |
| -Run a test on a specific file: |
| 82 | +This will create a virtual environment and install all necessary dependencies for development. |
| 83 | + |
| 84 | +## Using the Makefile |
| 85 | + |
| 86 | +We provide a comprehensive Makefile to streamline common development tasks. Here are the available commands: |
| 87 | + |
| 88 | +| Command | Description | |
| 89 | +|---------|-------------| |
| 90 | +| `make install` | Installs all dependencies using UV | |
| 91 | +| `make redis-start` | Starts Redis Stack in a Docker container on ports 6379 and 8001 | |
| 92 | +| `make redis-stop` | Stops the Redis Stack Docker container | |
| 93 | +| `make format` | Runs code formatting and import sorting | |
| 94 | +| `make check-types` | Runs mypy type checking | |
| 95 | +| `make lint` | Runs formatting, import sorting, and type checking | |
| 96 | +| `make test` | Runs tests, excluding those that require API keys and/or remote network calls | |
| 97 | +| `make test-all` | Runs all tests, including those that require API keys and/or remote network calls | |
| 98 | +| `make test-notebooks` | Runs all notebook tests | |
| 99 | +| `make check` | Runs all linting targets and a subset of tests | |
| 100 | +| `make docs-build` | Builds the documentation | |
| 101 | +| `make docs-serve` | Serves the documentation locally | |
| 102 | +| `make clean` | Removes all generated files (cache, coverage, build artifacts, etc.) | |
| 103 | + |
| 104 | +**Quick Start Example:** |
91 | 105 | ```bash
|
92 |
| -poetry run test-verbose tests/unit/test_fields.py |
| 106 | +# Set up the project |
| 107 | +make install |
| 108 | + |
| 109 | +# Start Redis Stack |
| 110 | +make redis-start |
| 111 | + |
| 112 | +# Run linting and tests |
| 113 | +make check |
| 114 | + |
| 115 | +# Stop Redis when done |
| 116 | +make redis-stop |
93 | 117 | ```
|
94 | 118 |
|
95 |
| -### Documentation |
96 |
| -Docs are served from the `docs/` directory. |
| 119 | +## Code Quality and Testing |
| 120 | + |
| 121 | +### Linting and Formatting |
| 122 | + |
| 123 | +We maintain high code quality standards. Before submitting your changes, ensure they pass our quality checks: |
97 | 124 |
|
98 |
| -Build the docs. Generates the `_build/html` contents: |
99 | 125 | ```bash
|
100 |
| -poetry run build-docs |
| 126 | +# Format code and sort imports |
| 127 | +make format |
| 128 | + |
| 129 | +# Check types |
| 130 | +make check-types |
| 131 | + |
| 132 | +# Or run all linting checks at once |
| 133 | +make lint |
101 | 134 | ```
|
102 | 135 |
|
103 |
| -Serve the documentation with a local webserver: |
| 136 | +You can also run these commands directly with UV: |
104 | 137 | ```bash
|
105 |
| -poetry run serve-docs |
| 138 | +uv run ruff format |
| 139 | +uv run ruff check --fix |
| 140 | +uv run mypy redisvl |
106 | 141 | ```
|
107 | 142 |
|
108 |
| -### Getting Redis |
| 143 | +### Running Tests |
| 144 | + |
| 145 | +#### TestContainers |
| 146 | + |
| 147 | +RedisVL uses [Testcontainers Python](https://testcontainers-python.readthedocs.io/) for integration tests. Testcontainers provisions throwaway, on-demand containers for development and testing. |
| 148 | + |
| 149 | +**Requirements:** |
| 150 | +- Local Docker installation such as: |
| 151 | + - [Docker Desktop](https://www.docker.com/products/docker-desktop/) |
| 152 | + - [Docker Engine on Linux](https://docs.docker.com/engine/install/) |
109 | 153 |
|
110 |
| -In order for your applications to use RedisVL, you must have [Redis](https://redis.io) accessible with Search & Query features enabled on [Redis Cloud](https://redis.io/cloud/) or locally in docker with [Redis Stack](https://redis.io/docs/latest/operate/oss_and_stack/install/install-stack/docker/): |
| 154 | +#### Test Commands |
111 | 155 |
|
112 | 156 | ```bash
|
113 |
| -docker run -d --name redis-stack -p 6379:6379 -p 8001:8001 redis/redis-stack:latest |
| 157 | +# Run tests without external API calls |
| 158 | +make test |
| 159 | + |
| 160 | +# Run all tests including those requiring API keys |
| 161 | +make test-all |
| 162 | + |
| 163 | +# Run tests on a specific file |
| 164 | +uv run pytest tests/unit/test_fields.py -v |
| 165 | + |
| 166 | +# Run tests with coverage |
| 167 | +uv run pytest --cov=redisvl --cov-report=html |
114 | 168 | ```
|
115 | 169 |
|
116 |
| -Or from your makefile simply run: |
| 170 | +**Note:** Tests requiring external APIs need appropriate API keys set as environment variables. |
| 171 | + |
| 172 | +## Documentation |
| 173 | + |
| 174 | +Documentation is served from the `docs/` directory and built using Sphinx. |
| 175 | + |
| 176 | +### Building and Serving Docs |
117 | 177 |
|
118 | 178 | ```bash
|
119 |
| -make redis-start |
| 179 | +# Build the documentation |
| 180 | +make docs-build |
| 181 | + |
| 182 | +# Serve documentation locally at http://localhost:8000 |
| 183 | +make docs-serve |
120 | 184 | ```
|
121 | 185 |
|
122 |
| -And then: |
| 186 | +Or using UV directly: |
| 187 | +```bash |
| 188 | +# Build docs |
| 189 | +uv run sphinx-build -b html docs docs/_build/html |
| 190 | + |
| 191 | +# Serve docs |
| 192 | +uv run python -m http.server 8000 --directory docs/_build/html |
| 193 | +``` |
| 194 | + |
| 195 | +## Redis Setup |
| 196 | + |
| 197 | +To develop and test RedisVL applications, you need Redis with Search & Query features. You have several options: |
| 198 | + |
| 199 | +### Option 1: Redis Stack with Docker (Recommended for Development) |
| 200 | + |
123 | 201 | ```bash
|
| 202 | +# Start Redis Stack with RedisInsight GUI |
| 203 | +make redis-start |
| 204 | + |
| 205 | +# This runs: |
| 206 | +# docker run -d --name redis-stack -p 6379:6379 -p 8001:8001 redis/redis-stack:latest |
| 207 | + |
| 208 | +# Stop when finished |
124 | 209 | make redis-stop
|
125 | 210 | ```
|
126 | 211 |
|
127 |
| -This will also spin up the [FREE RedisInsight GUI](https://redis.io/insight/) at `http://localhost:8001`. |
| 212 | +This also provides the [FREE RedisInsight GUI](https://redis.io/insight/) at `http://localhost:8001`. |
| 213 | + |
| 214 | +### Option 2: Redis Cloud |
128 | 215 |
|
129 |
| -## How to Report a Bug |
| 216 | +For production-like testing, use [Redis Cloud](https://redis.io/cloud/) which provides managed Redis instances with Search & Query capabilities. |
| 217 | + |
| 218 | +## Reporting Issues |
130 | 219 |
|
131 | 220 | ### Security Vulnerabilities
|
132 | 221 |
|
133 |
| -**NOTE**: If you find a security vulnerability, do NOT open an issue. |
134 |
| -Email [Redis OSS (<oss@redis.com>)](mailto:oss@redis.com) instead. |
| 222 | +**⚠️ IMPORTANT**: If you find a security vulnerability, do NOT open a public issue. Email [Redis OSS](mailto:oss@redis.com) instead. |
| 223 | + |
| 224 | +**Questions to determine if it's a security issue:** |
| 225 | +- Can I access something that's not mine, or something I shouldn't have access to? |
| 226 | +- Can I disable something for other people? |
| 227 | + |
| 228 | +If you answer *yes* to either question, it's likely a security issue. |
| 229 | + |
| 230 | +### Bug Reports |
| 231 | + |
| 232 | +When filing a bug report, please include: |
| 233 | + |
| 234 | +1. **Python version**: What version of Python are you using? |
| 235 | +2. **Package versions**: What versions of `redis` and `redisvl` are you using? |
| 236 | +3. **Steps to reproduce**: What did you do? |
| 237 | +4. **Expected behavior**: What did you expect to see? |
| 238 | +5. **Actual behavior**: What did you see instead? |
| 239 | +6. **Environment**: Operating system, Docker version (if applicable) |
| 240 | +7. **Code sample**: Minimal code that reproduces the issue |
| 241 | + |
| 242 | +## Suggesting Features |
| 243 | + |
| 244 | +Before suggesting a new feature: |
| 245 | + |
| 246 | +1. **Check existing issues**: Search our [issue list](https://github.com/redis/redis-vl-python/issues) to see if someone has already proposed it |
| 247 | +2. **Consider the scope**: Ensure the feature aligns with RedisVL's goals |
| 248 | +3. **Provide details**: If you don't see anything similar, open a new issue that describes: |
| 249 | + - The feature you would like |
| 250 | + - How it should work |
| 251 | + - Why it would be beneficial |
| 252 | + - Any implementation ideas you have |
135 | 253 |
|
136 |
| -In order to determine whether you are dealing with a security issue, ask |
137 |
| -yourself these two questions: |
| 254 | +## Pull Request Process |
138 | 255 |
|
139 |
| -- Can I access something that's not mine, or something I shouldn't |
140 |
| - have access to? |
141 |
| -- Can I disable something for other people? |
| 256 | +1. **Fork and create a branch**: Create a descriptive branch name (e.g., `fix-search-bug` or `add-vector-similarity`) |
| 257 | +2. **Make your changes**: Follow our coding standards and include tests |
| 258 | +3. **Test thoroughly**: Ensure your changes work and don't break existing functionality |
| 259 | +4. **Update documentation**: Add or update documentation as needed |
| 260 | +5. **Submit your PR**: Include a clear description of what your changes do |
142 | 261 |
|
143 |
| -If the answer to either of those two questions are *yes*, then you're |
144 |
| -probably dealing with a security issue. Note that even if you answer |
145 |
| -*no* to both questions, you may still be dealing with a security |
146 |
| -issue, so if you're unsure, just email us. |
| 262 | +### Review Process |
147 | 263 |
|
148 |
| -### Everything Else |
| 264 | +- The core team reviews Pull Requests regularly |
| 265 | +- We provide feedback as soon as possible |
| 266 | +- After feedback, we expect a response within two weeks |
| 267 | +- PRs may be closed if they show no activity after this period |
149 | 268 |
|
150 |
| -When filing an issue, make sure to answer these five questions: |
| 269 | +### PR Checklist |
151 | 270 |
|
152 |
| -1. What version of python are you using? |
153 |
| -2. What version of `redis` and `redisvl` are you using? |
154 |
| -3. What did you do? |
155 |
| -4. What did you expect to see? |
156 |
| -5. What did you see instead? |
| 271 | +Before submitting your PR, ensure: |
157 | 272 |
|
158 |
| -## How to Suggest a Feature or Enhancement |
| 273 | +- [ ] Code follows our style guidelines (`make lint` passes) |
| 274 | +- [ ] Tests pass (`make test` passes) |
| 275 | +- [ ] Documentation is updated if needed |
| 276 | +- [ ] Commit messages are clear and descriptive |
| 277 | +- [ ] PR description explains what changes were made and why |
159 | 278 |
|
160 |
| -If you'd like to contribute a new feature, make sure you check our |
161 |
| -issue list to see if someone has already proposed it. Work may already |
162 |
| -be under way on the feature you want -- or we may have rejected a |
163 |
| -feature like it already. |
| 279 | +## Getting Help |
164 | 280 |
|
165 |
| -If you don't see anything, open a new issue that describes the feature |
166 |
| -you would like and how it should work. |
| 281 | +If you need help or have questions: |
167 | 282 |
|
168 |
| -## Code Review Process |
| 283 | +- **Issues**: Open an issue for bugs or feature requests |
| 284 | +- **Discussions**: Use GitHub Discussions for general questions |
| 285 | +- **Documentation**: Check our [documentation](https://www.redisvl.com/) for guides and examples |
169 | 286 |
|
170 |
| -The core team looks at Pull Requests on a regular basis. We will give |
171 |
| -feedback as as soon as possible. After feedback, we expect a response |
172 |
| -within two weeks. After that time, we may close your PR if it isn't |
173 |
| -showing any activity. |
| 287 | +Thank you for contributing to RedisVL! 🚀 |
0 commit comments