Contributing - Manticore CockroachDB Client
Description: A Python client for CockroachDB with sync and async support

Skip to content

# Contributing to Manticore CockroachDB

Thank you for your interest in contributing to the Manticore CockroachDB client! This document provides guidelines and instructions for contributing to the project.

## Development Setup

1. Clone the repository:

       git clone https://github.com/manticoretechnology/manticore-cockroachdb.git
       cd manticore-cockroachdb

2. Create a virtual environment and install development dependencies:

       python -m venv venv
       source venv/bin/activate  # On Windows: venv\Scripts\activate
       pip install -e ".[dev,docs]"

3. Install pre-commit hooks (recommended):

       pip install pre-commit
       pre-commit install

## Development Workflow

1. Create a new branch for your feature or bugfix:

       git checkout -b feature/your-feature-name
       # or
       git checkout -b fix/your-bugfix-name

2. Make your changes, ensuring you follow the code style guidelines

3. Add tests for your changes

4. Run the tests to make sure everything works:

       pytest

5. Run type checking:

       mypy manticore_cockroachdb

6. Format your code:

       black manticore_cockroachdb tests
       isort manticore_cockroachdb tests

7. Commit your changes with a descriptive message:

       git commit -am "Add new feature: your feature description"

8. Push your branch and create a pull request

## Code Style Guidelines

- Follow PEP 8 style guide
- Use Black for code formatting
- Sort imports with isort
- Include type annotations for all function parameters and return values
- Write docstrings in the Google style format

## Testing

- Write tests for all new features and bug fixes
- Ensure all tests pass before submitting a pull request
- Aim for high test coverage (>90%)
- Include both synchronous and asynchronous tests where applicable

## Documentation

- Update documentation for any new features or changes to existing functionality
- Documentation is built with MkDocs and the Material theme
- To preview documentation locally:

      mkdocs serve

- Document all public API methods with clear examples

## Submitting a Pull Request

1. Ensure your code passes all tests and quality checks
2. Update documentation as needed
3. Include a clear description of the changes in your pull request
4. Link any related issues in the pull request description
5. Wait for code review and address any feedback

## Building and releasing

1. Ensure all tests pass
2. Update version number in:
3. `manticore_cockroachdb/__init__.py`
4. `setup.py`
5. `pyproject.toml`
6. Update `CHANGELOG.md` with the new version and changes
7. Build the package:

       python -m build

8. Test the built package:

       pip install dist/*.whl

9. Upload to PyPI (maintainers only):

       twine upload dist/*

## Code of Conduct

Please be respectful and considerate of others when contributing to the project. We aim to create a welcoming and inclusive environment for all contributors.