feat: add pre-commit configuration and contributing guide

.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+        exclude: ^opensource/
+      - id: end-of-file-fixer
+        exclude: ^opensource/
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+        files: ^(src|benchmarks|tests|examples|tools)/

CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing to dynavec
+
+Thank you for your interest in contributing to **dynavec**! We welcome bug fixes, documentation improvements, test additions, and new features.
+
+---
+
+## Getting Started
+
+### 1. Fork and Clone
+Fork the repository on GitHub, then clone your fork locally:
+```bash
+git clone https://github.com/<your-username>/dynavec.git
+cd dynavec
+git remote add upstream https://github.com/codeforstartups/dynavec.git
+```
+
+### 2. Set Up a Virtual Environment
+Create and activate a virtual environment (Python 3.9+):
+```bash
+# macOS / Linux
+python3 -m venv .venv
+source .venv/bin/activate
+
+# Windows (PowerShell)
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+```
+
+### 3. Install Dependencies in Editable Mode
+Install the package along with developer tools:
+```bash
+pip install -e ".[dev]"
+```
+
+---
+
+## Pre-commit Hooks
+
+We use [pre-commit](https://pre-commit.com/) to automatically enforce code style and formatting (`ruff`, trailing whitespace, end-of-file newlines, and valid YAML/TOML).
+
+### Install the Hooks
+After installing `.[dev]`, set up pre-commit to run on every `git commit`:
+```bash
+pre-commit install
+```
+
+### Run Manually on All Files
+You can run all hooks across the codebase at any time:
+```bash
+pre-commit run --all-files
+```
+
+---
+
+## Running Tests and Linting
+
+Before pushing changes or submitting a Pull Request, make sure all tests pass and code checks succeed:
+
+### Run Linter and Formatter
+```bash
+# Check code with ruff
+ruff check src benchmarks tests
+
+# Auto-fix lint issues where possible
+ruff check --fix src benchmarks tests
+
+# Format code
+ruff format src benchmarks tests
+```
+
+### Run the Test Suite
+```bash
+pytest
+```
+
+---
+
+## Making Changes & Submitting a PR
+
+1. **Branching**: Always branch off the `development` branch:
+   ```bash
+   git checkout development
+   git pull upstream development
+   git checkout -b feat/your-feature-name
+   ```
+
+2. **Commit Messages**: Follow [Conventional Commits](https://www.conventionalcommits.org/) (e.g., `feat:`, `fix:`, `docs:`, `test:`, `ci:`).
+
+3. **Rebasing**: Keep your branch up to date with `upstream/development` without merge commits:
+   ```bash
+   git fetch upstream development
+   git rebase upstream/development
+   ```
+
+4. **Pull Request**: Open your PR targeting the `development` branch of `codeforstartups/dynavec` and reference any related issue with `Closes #<issue_number>`.

pyproject.toml

@@ -70,6 +70,7 @@ dev = [
     "pytest-cov>=5.0",
     "moto[dynamodb]>=5.0",
     "ruff>=0.6",
+    "pre-commit>=3.5",
 ]
 benchmark = [
     "pandas>=2.0",

tests/test_cli.py

@@ -78,4 +78,4 @@ def test_doctor_requires_bucket_and_index_together(monkeypatch, capsys):
 
 def test_main_without_command_prints_help(capsys):
     assert cli.main([]) == 0
-    assert "doctor" in capsys.readouterr().out
+    assert "doctor" in capsys.readouterr().out

tests/test_client_inmemory.py

@@ -234,7 +234,7 @@ def test_ns_tag_present_in_s3(db):
     db.upsert([Document(id="1", text="hello")], namespace="ns9")
     # reach into the fake to confirm the namespace tag was written
     store = db._vectors._store
-    (_, meta), = [v for k, v in store.items()]
+    (_, meta), = (v for k, v in store.items())
     assert meta[NS_METADATA_KEY] == "ns9"
 
 

tests/test_ingest.py

@@ -105,4 +105,4 @@ def test_ingest_deduplicates_identical_chunks_within_run():
     assert [document.text for document in db.documents] == [
         "duplicate text",
         "unique text",
-    ]
+    ]