Contributing¶

Thank you for your interest in contributing to langchain-cockroachdb!

Development Setup¶

1. Fork and Clone¶

# Fork on GitHub, then clone
git clone https://github.com/YOUR_USERNAME/langchain-cockroachdb.git
cd langchain-cockroachdb

2. Install Dependencies¶

# Install with dev dependencies
pip install -e ".[dev]"

# Or with uv (recommended)
uv pip install -e ".[dev]"

3. Start CockroachDB¶

docker-compose up -d

4. Run Tests¶

make test

Development Workflow¶

1. Create a Branch¶

git checkout -b feature/your-feature-name

2. Make Changes¶

Follow the code style guidelines below.

3. Run Checks¶

# Run all checks
make all

# Or individually:
make lint      # Linting
make format    # Formatting
make typecheck # Type checking
make test      # Tests

4. Commit Changes¶

git add .
git commit -m "feat: add new feature"

Follow Conventional Commits: - feat: New feature - fix: Bug fix - docs: Documentation - test: Tests - refactor: Code refactoring - chore: Maintenance

5. Push and Create PR¶

git push origin feature/your-feature-name

Then create a Pull Request on GitHub.

Code Style¶

Python Style¶

Follow PEP 8
Use type hints
Maximum line length: 100 characters
Use async/await for I/O operations

# Good
async def add_documents(
    self,
    texts: list[str],
    metadatas: list[dict] | None = None,
) -> list[str]:
    """Add documents to the vector store.

    Args:
        texts: List of document texts
        metadatas: Optional metadata for each document

    Returns:
        List of document IDs
    """
    # Implementation

Linting¶

# Auto-fix most issues
make format

# Check linting
make lint

Type Checking¶

make typecheck

Testing¶

Test Structure¶

tests/
├── unit/           # Fast tests, no database
└── integration/    # Tests with CockroachDB

Writing Tests¶

import pytest
from langchain_cockroachdb import AsyncCockroachDBVectorStore

class TestVectorStore:
    @pytest.mark.asyncio
    async def test_add_texts(self, vectorstore):
        """Test adding texts to vector store."""
        texts = ["doc1", "doc2"]
        ids = await vectorstore.aadd_texts(texts)

        assert len(ids) == 2
        assert all(isinstance(id, str) for id in ids)

Running Tests¶

# All tests
make test

# Unit tests only
pytest tests/unit -v

# Specific test
pytest tests/unit/test_indexes.py::TestCSPANNIndex::test_index_creation -v

# With coverage
pytest tests --cov=langchain_cockroachdb --cov-report=html

Test Requirements¶

✅ Tests must pass
✅ Coverage should not decrease
✅ Use fixtures for common setup
✅ Mock external services when possible

Documentation¶

Docstrings¶

Use Google-style docstrings:

def function(arg1: str, arg2: int = 10) -> bool:
    """Short description.

    Longer description if needed.

    Args:
        arg1: Description
        arg2: Description (default: 10)

    Returns:
        Description

    Raises:
        ValueError: Description

    Example:
        ```python
        result = function("value", arg2=20)
        ```
    """

Documentation Site¶

# Install docs dependencies
pip install -e ".[docs]"

# Serve locally
mkdocs serve

# Build
mkdocs build

Adding Documentation¶

Update relevant guide in docs/guides/
Add examples to examples/
Update README.md if needed

Pull Request Guidelines¶

PR Checklist¶

[ ] Tests pass (make test)
[ ] Linting passes (make lint)
[ ] Type checking passes (make typecheck)
[ ] Documentation updated
[ ] CHANGELOG.md updated
[ ] Commit messages follow Conventional Commits

PR Description Template¶

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
How were the changes tested?

## Checklist
- [ ] Tests pass
- [ ] Linting passes
- [ ] Documentation updated

Release Process¶

Maintainers only:

Update version in pyproject.toml
Update CHANGELOG.md
Create git tag
Push to GitHub
GitHub Actions builds and publishes to PyPI

Getting Help¶

Issues: GitHub Issues
Discussions: GitHub Discussions

Code of Conduct¶

Be respectful and inclusive. See CODE_OF_CONDUCT.md.

License¶

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.