From 3742ba0e91bd6f16d44ebb16d4d7cb06db0c0134 Mon Sep 17 00:00:00 2001
From: Ashish Singh <Ashishsingh0045@gmail.com>
Date: Tue, 8 Sep 2026 06:47:20 +0530
Subject: [PATCH] feat: add pre-commit configuration and contributing guide

---
 .pre-commit-config.yaml       | 18 +++++++
 CONTRIBUTING.md               | 95 +++++++++++++++++++++++++++++++++++
 pyproject.toml                |  1 +
 tests/test_cli.py             |  2 +-
 tests/test_client_inmemory.py |  2 +-
 tests/test_ingest.py          |  2 +-
 6 files changed, 117 insertions(+), 3 deletions(-)
 create mode 100644 .pre-commit-config.yaml
 create mode 100644 CONTRIBUTING.md

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
new file mode 100644
index 0000000..b803c01
--- /dev/null
+++ b/.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)/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..5fc62e4
--- /dev/null
+++ b/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>`.
diff --git a/pyproject.toml b/pyproject.toml
index aafc18b..77011b2 100644
--- a/pyproject.toml
+++ b/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",
diff --git a/tests/test_cli.py b/tests/test_cli.py
index a8869b3..b519f55 100644
--- a/tests/test_cli.py
+++ b/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
\ No newline at end of file
+    assert "doctor" in capsys.readouterr().out
diff --git a/tests/test_client_inmemory.py b/tests/test_client_inmemory.py
index adfc41d..5087356 100644
--- a/tests/test_client_inmemory.py
+++ b/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"
 
 
diff --git a/tests/test_ingest.py b/tests/test_ingest.py
index d86c423..a2eabf1 100644
--- a/tests/test_ingest.py
+++ b/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",
-    ]
\ No newline at end of file
+    ]