Skip to content

Commit aab2747

Browse files
atasogluatasoglu
committed
feat(docs): add CONTRIBUTING and CHANGELOG files
- Create CONTRIBUTING.md with contribution guidelines - Create CHANGELOG.md for tracking project changes - Update README.md to link to new documentation files - Add badges for PyPI, Python version, license, and code style in README
1 parent fbf0d6e commit aab2747

File tree

4 files changed

+334
-6
lines changed

4 files changed

+334
-6
lines changed

‎CHANGELOG.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [Unreleased]
9+
10+
### Added
11+
- CONTRIBUTING.md with contribution guidelines
12+
- CHANGELOG.md for tracking changes
13+
14+
## [0.1.0] - 2025-01-XX
15+
16+
### Added
17+
- Initial release of sqlite-vec-client
18+
- `SQLiteVecClient` class for CRUD and similarity search operations
19+
- Support for text, metadata (JSON), and float32 embeddings
20+
- Automatic synchronization between base table and vec0 index via triggers
21+
- Context manager support for automatic connection cleanup
22+
- Comprehensive test suite with 91%+ coverage
23+
- Security features: SQL injection prevention, input validation
24+
- Custom exception classes for better error handling
25+
- Type hints and dataclasses for typed results
26+
- Examples demonstrating various use cases
27+
- Development tooling: ruff, mypy, pre-commit hooks
28+
29+
### Core Features
30+
- `create_table()` - Initialize schema with configurable dimensions and distance metrics
31+
- `add()` - Insert texts with embeddings
32+
- `update()` - Update existing records
33+
- `delete()` - Remove records by rowid
34+
- `get()` - Fetch single record by rowid
35+
- `get_many()` - Fetch multiple records
36+
- `get_by_text()` - Find records by exact text match
37+
- `get_by_metadata()` - Find records by metadata JSON match
38+
- `list_all()` - List all records with pagination
39+
- `similarity_search()` - Vector similarity search with configurable top_k
40+
- `count()` - Get total record count
41+
- `clear()` - Remove all records
42+
- `drop_table()` - Delete table and index
43+
44+
### Distance Metrics
45+
- Cosine similarity (`cosine`)
46+
- L2 distance (`l2`)
47+
- L1 distance (`l1`)
48+
49+
### Documentation
50+
- Comprehensive README with quick start guide
51+
- TESTING.md with testing documentation
52+
- SECURITY_IMPROVEMENTS.md documenting security enhancements
53+
- Multiple examples in `examples/` directory
54+
55+
### Dependencies
56+
- Python 3.9+
57+
- SQLite 3.41+
58+
- sqlite-vec 0.1.6+
59+
60+
## [0.0.1] - 2025-01-XX (Pre-release)
61+
62+
### Added
63+
- Initial project structure
64+
- Basic SQLiteVecClient implementation
65+
- Proof of concept
66+
67+
---
68+
69+
## Version History
70+
71+
- **0.1.0** - First stable release with comprehensive features and testing
72+
- **0.0.1** - Initial development version
73+
74+
## Upgrade Guide
75+
76+
### From 0.0.x to 0.1.0
77+
78+
No breaking changes. This is the first stable release.
79+
80+
---
81+
82+
## Contributing
83+
84+
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on contributing to this project.
85+
86+
## Links
87+
88+
- [GitHub Repository](https://github.com/atasoglu/sqlite-vec-client)
89+
- [PyPI Package](https://pypi.org/project/sqlite-vec-client/)
90+
- [Issue Tracker](https://github.com/atasoglu/sqlite-vec-client/issues)

‎CONTRIBUTING.md‎

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
# Contributing to sqlite-vec-client
2+
3+
Thank you for your interest in contributing! This document provides guidelines and instructions for contributing to the project.
4+
5+
## Code of Conduct
6+
7+
Be respectful, constructive, and professional in all interactions.
8+
9+
## Getting Started
10+
11+
### Prerequisites
12+
13+
- Python 3.9+
14+
- SQLite 3.41+
15+
- Git
16+
17+
### Setup Development Environment
18+
19+
1. Fork and clone the repository:
20+
```bash
21+
git clone https://github.com/YOUR_USERNAME/sqlite-vec-client.git
22+
cd sqlite-vec-client
23+
```
24+
25+
2. Install development dependencies:
26+
```bash
27+
pip install -r requirements-dev.txt
28+
```
29+
30+
3. Install pre-commit hooks:
31+
```bash
32+
pre-commit install
33+
```
34+
35+
## Development Workflow
36+
37+
### 1. Create a Branch
38+
39+
```bash
40+
git checkout -b feature/your-feature-name
41+
# or
42+
git checkout -b fix/your-bug-fix
43+
```
44+
45+
### 2. Make Changes
46+
47+
- Write clean, readable code
48+
- Follow existing code style
49+
- Add tests for new features
50+
- Update documentation as needed
51+
52+
### 3. Run Tests
53+
54+
```bash
55+
# Run all tests
56+
pytest
57+
58+
# Run with coverage
59+
pytest --cov=sqlite_vec_client --cov-report=html
60+
61+
# Run specific test categories
62+
pytest -m unit
63+
pytest -m integration
64+
```
65+
66+
### 4. Code Quality Checks
67+
68+
```bash
69+
# Format code
70+
ruff format .
71+
72+
# Lint code
73+
ruff check .
74+
75+
# Type checking
76+
mypy sqlite_vec_client/
77+
78+
# Run all checks
79+
ruff check . && ruff format . && mypy sqlite_vec_client/ && pytest
80+
```
81+
82+
### 5. Commit Changes
83+
84+
```bash
85+
git add .
86+
git commit -m "feat: add new feature"
87+
# or
88+
git commit -m "fix: resolve bug"
89+
```
90+
91+
**Commit message format:**
92+
- `feat:` New feature
93+
- `fix:` Bug fix
94+
- `docs:` Documentation changes
95+
- `test:` Test additions or changes
96+
- `refactor:` Code refactoring
97+
- `chore:` Maintenance tasks
98+
99+
### 6. Push and Create Pull Request
100+
101+
```bash
102+
git push origin your-branch-name
103+
```
104+
105+
Then create a pull request on GitHub.
106+
107+
## Pull Request Guidelines
108+
109+
### Before Submitting
110+
111+
- [ ] Tests pass locally
112+
- [ ] Code is formatted (ruff format)
113+
- [ ] No linting errors (ruff check)
114+
- [ ] Type checking passes (mypy)
115+
- [ ] Documentation is updated
116+
- [ ] CHANGELOG.md is updated (if applicable)
117+
118+
### PR Description
119+
120+
Include:
121+
- What changes were made
122+
- Why the changes were needed
123+
- How to test the changes
124+
- Related issue numbers (if any)
125+
126+
## Testing Guidelines
127+
128+
### Writing Tests
129+
130+
- Place tests in the `tests/` directory
131+
- Use descriptive test names: `test_<function>_<scenario>_<expected_result>`
132+
- Use pytest fixtures from `conftest.py`
133+
- Mark tests appropriately: `@pytest.mark.unit` or `@pytest.mark.integration`
134+
135+
### Test Coverage
136+
137+
- Aim for 80%+ coverage
138+
- Test edge cases and error conditions
139+
- Include security tests for user inputs
140+
141+
## Code Style
142+
143+
### Python Style
144+
145+
- Follow PEP 8
146+
- Use type hints
147+
- Maximum line length: 88 characters (Black default)
148+
- Use descriptive variable names
149+
150+
### Documentation Style
151+
152+
- Docstrings for all public functions/classes
153+
- Use Google-style docstrings
154+
- Include examples in docstrings when helpful
155+
156+
Example:
157+
```python
158+
def add(self, texts: list[str], embeddings: list[list[float]]) -> list[int]:
159+
"""Add texts with embeddings to the database.
160+
161+
Args:
162+
texts: List of text strings to store.
163+
embeddings: List of embedding vectors (one per text).
164+
165+
Returns:
166+
List of rowids for the inserted records.
167+
168+
Raises:
169+
VecClientError: If insertion fails.
170+
"""
171+
```
172+
173+
## Reporting Issues
174+
175+
### Bug Reports
176+
177+
Include:
178+
- Python version
179+
- SQLite version
180+
- sqlite-vec version
181+
- Minimal code to reproduce
182+
- Expected vs actual behavior
183+
- Error messages/stack traces
184+
185+
### Feature Requests
186+
187+
Include:
188+
- Use case description
189+
- Proposed API (if applicable)
190+
- Why existing features don't solve the problem
191+
192+
## Project Structure
193+
194+
```
195+
sqlite-vec-client/
196+
├── sqlite_vec_client/ # Main package
197+
│ ├── __init__.py # Public API
198+
│ ├── base.py # SQLiteVecClient class
199+
│ ├── exceptions.py # Custom exceptions
200+
│ ├── types.py # Type definitions
201+
│ ├── utils.py # Utility functions
202+
│ └── validation.py # Input validation
203+
├── tests/ # Test suite
204+
├── examples/ # Usage examples
205+
└── docs/ # Documentation (future)
206+
```
207+
208+
## Areas for Contribution
209+
210+
Check the [TODO](TODO) file for tasks. Good starting points:
211+
212+
- Documentation improvements
213+
- Additional examples
214+
- Test coverage improvements
215+
- Bug fixes
216+
- Performance optimizations
217+
218+
## Questions?
219+
220+
- Open an issue for questions
221+
- Check existing issues and PRs first
222+
- Be patient and respectful
223+
224+
## License
225+
226+
By contributing, you agree that your contributions will be licensed under the MIT License.

‎README.md‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
# sqlite-vec-client
22

3+
[![PyPI version](https://badge.fury.io/py/sqlite-vec-client.svg)](https://badge.fury.io/py/sqlite-vec-client)
4+
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
5+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6+
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
7+
38
A tiny, lightweight Pythonic helper around [sqlite-vec](https://github.com/asg017/sqlite-vec) that lets you store texts, JSON metadata, and float32 embeddings in SQLite and run fast similarity search.
49

510
## Features
@@ -137,9 +142,17 @@ mypy sqlite_vec_client/
137142
ruff check . && ruff format . && mypy sqlite_vec_client/ && pytest
138143
```
139144

145+
## Documentation
146+
147+
- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribution guidelines
148+
- [CHANGELOG.md](CHANGELOG.md) - Version history
149+
- [TESTING.md](TESTING.md) - Testing documentation
150+
- [Examples](examples/) - Usage examples
151+
140152
## Contributing
141-
Contributions are very welcome—issues, ideas, and PRs help this project grow!
153+
154+
Contributions are very welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
142155

143156
## License
144157

145-
MIT
158+
MIT - See [LICENSE](LICENSE) for details.

‎TODO‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,11 +32,10 @@
3232
- [x] examples/real_world_scenario.py
3333

3434
### Documentation
35-
- [ ] Create CONTRIBUTING.md
36-
- [ ] Start CHANGELOG.md
35+
- [x] Create CONTRIBUTING.md
36+
- [x] Start CHANGELOG.md
3737
- [ ] API reference documentation (Sphinx or MkDocs)
3838
- [ ] Migration guide (for version updates)
39-
- [ ] Add troubleshooting section
4039

4140
## 🟢 Medium Priority (Development & Tooling)
4241

@@ -87,7 +86,7 @@
8786

8887
## 📝 Documentation Improvements
8988

90-
- [ ] Add badges to README (PyPI, tests, coverage, license)
89+
- [x] Add badges to README (PyPI, tests, coverage, license)
9190
- [ ] Publish performance benchmarks
9291
- [ ] Comparison with alternatives (Chroma, Qdrant, etc.)
9392
- [ ] Add architecture diagram

0 commit comments

Comments
 (0)