Contributing
============

We welcome contributions to the MatrixOne Python SDK! This document provides guidelines for contributing to the project.

Getting Started
---------------

1. Fork the repository on GitHub
2. Clone your fork locally

   .. code-block:: bash

      git clone https://github.com/matrixorigin/matrixone
      cd matrixone/clients/python-wrapper

3. Set up development environment

   .. code-block:: bash

      # Create virtual environment
      python -m venv venv
      source venv/bin/activate  # On macOS/Linux

      # Install development dependencies
      make dev-setup

4. Create a feature branch

   .. code-block:: bash

      git checkout -b feature/your-feature-name

Development Workflow
--------------------

Code Style
~~~~~~~~~~

We use several tools to maintain code quality:

* **Black**: Code formatting
* **isort**: Import sorting
* **flake8**: Linting
* **mypy**: Type checking

Run all checks

   .. code-block:: bash

   make pre-commit-full

Or run individual checks

   .. code-block:: bash

   make format    # Format code
   make lint      # Run linting
   make type-check # Type checking

Testing
~~~~~~~

Write tests for new features and bug fixes

   .. code-block:: bash

   # Run all tests
   make test

   # Run specific test file
    python -m pytest test_client.py -v

   # Run with coverage
    python -m pytest --cov=matrixone test_*.py

Documentation
~~~~~~~~~~~~~

Update documentation for new features

   .. code-block:: bash

   # Generate documentation
   make docs

   # Serve documentation locally
   make docs-serve

Documentation Guidelines
~~~~~~~~~~~~~~~~~~~~~~~~

* Use Google-style docstrings for all public methods
* Include examples in docstrings where appropriate
* Update API documentation in ``docs/api/``
* Add examples to ``docs/examples.rst``

Example docstring

   .. code-block:: bash

   def create_snapshot(self, name: str, level: str) -> Snapshot:
       """
       Create a new database snapshot.

       Args:
           name (str): Name of the snapshot
           level (str): Snapshot level ('cluster', 'database', 'table')

       Returns:
           Snapshot: Created snapshot object

       Raises:
           SnapshotError: If snapshot creation fails
           VersionError: If feature not supported

       Examples:
           >>> snapshot = client.snapshots.create('backup', 'cluster')
           >>> print(snapshot.name)
           backup

       """
       # Implementation here

Pull Request Process
--------------------

1. Ensure all tests pass

   .. code-block:: bash

   make test

2. Run code quality checks

   .. code-block:: bash

   make pre-commit-full

3. Update documentation if needed

   .. code-block:: bash

   make docs

4. Commit your changes

   .. code-block:: bash

   git add .
   git commit -m "Add feature: brief description"

5. Push to your fork

   .. code-block:: bash

   git push origin feature/your-feature-name

6. Create a Pull Request on GitHub

Pull Request Guidelines
~~~~~~~~~~~~~~~~~~~~~~~

* Provide a clear description of changes
* Reference any related issues
* Include tests for new functionality
* Update documentation as needed
* Ensure CI passes

Issue Reporting
---------------

When reporting issues, please include:

* Python version
* MatrixOne version
* Operating system
* Steps to reproduce
* Expected vs actual behavior
* Error messages/logs

Code Review Process
-------------------

* All PRs require review from maintainers
* Address review feedback promptly
* Keep PRs focused and reasonably sized
* Squash commits before merging

Release Process
---------------

Releases are managed by maintainers:

1. Update version in ``pyproject.toml``
2. Update ``CHANGELOG.md``
3. Create release tag
4. Build and publish to PyPI

   .. code-block:: bash

   make publish

Development Tools
-----------------

Useful commands for development

   .. code-block:: bash

   make help              # Show all available commands
   make check-env         # Check Python environment
   make clean             # Clean build artifacts
   make build             # Build package
   make examples          # Run example scripts

Environment Variables
~~~~~~~~~~~~~~~~~~~~~

You can override default Python paths

   .. code-block:: bash

   export PYTHON=/path/to/python3
   export PIP=/path/to/pip
   make test

Or pass them directly

   .. code-block:: bash

   make test PYTHON=/path/to/python3

Community Guidelines
--------------------

* Be respectful and inclusive
* Help others learn and grow
* Follow the code of conduct
* Ask questions in discussions or issues

Getting Help
------------

* Check existing issues and discussions
* Join our community channels
* Ask questions in GitHub discussions
* Contact maintainers for urgent issues

Thank you for contributing to MatrixOne Python SDK! 🚀