Contributing to TRX-Python#

We welcome contributions from the community! This guide will help you get started with contributing to the TRX-Python project.

Ways to Contribute#

There are many ways to contribute to TRX-Python:

Report bugs: If you find a bug, please open an issue on GitHub
Suggest features: Have an idea? Open an issue to discuss it
Fix bugs: Look for issues labeled “good first issue” or “help wanted”
Write documentation: Help improve our docs or add examples
Write tests: Increase test coverage
Code review: Review pull requests from other contributors

Getting Started#

Fork the repository on GitHub

Clone your fork:

git clone https://github.com/YOUR_USERNAME/trx-python.git
cd trx-python

Set up development environment:
```
pip install -e ".[all]"
spin setup
```
The spin setup command fetches version tags from upstream, which is required for correct version detection.
Create a branch for your changes:
```
git checkout -b my-feature-branch
```

Making Changes#

Development Workflow#

We use spin for development workflow:

spin install    # Install in editable mode
spin test       # Run all tests
spin lint       # Run linting (ruff)
spin docs       # Build documentation

Before Submitting#

Run tests to ensure your changes don’t break existing functionality:
```
spin test
```
Run linting to ensure code style compliance:
```
spin lint
```
You can auto-fix many issues with:
```
spin lint --fix
```
Format your code using ruff:
```
ruff format .
```
Write tests for any new functionality
Update documentation if needed

Submitting a Pull Request#

Push your changes to your fork:
```
git push origin my-feature-branch
```
Open a Pull Request on GitHub against the master branch
Describe your changes in the PR description:
- What does this PR do?
- Why is this change needed?
- How was it tested?
Wait for CI checks to pass
Address review feedback if requested

Code Style#

We follow these conventions:

PEP 8 style guide
Line length: 88 characters maximum
Docstrings: NumPy style format
Type hints: Encouraged but not required

Example docstring:

def my_function(param1, param2):
    """Short description of the function.

    Parameters
    ----------
    param1 : int
        Description of param1.
    param2 : str
        Description of param2.

    Returns
    -------
    result : bool
        Description of return value.

    Examples
    --------
    >>> my_function(1, "test")
    True
    """
    pass

We use ruff for linting and formatting. Configuration is in ruff.toml.

Testing#

Tests are located in trx/tests/. We use pytest for testing.

Running Tests#

# Run all tests
spin test

# Run tests matching a pattern
spin test -m memmap

# Run with verbose output
spin test -v

# Run a specific test file
pytest trx/tests/test_memmap.py

Writing Tests#

Place tests in trx/tests/
Name test files test_*.py
Name test functions test_*
Use pytest fixtures for common setup

Documentation#

Documentation is built with Sphinx and hosted on GitHub Pages.

Building Docs#

spin docs              # Build documentation
spin docs --clean      # Clean build
spin docs --open       # Build and open in browser

Writing Documentation#

Documentation source is in docs/source/
Use reStructuredText format
API documentation is auto-generated from docstrings

Getting Help#

GitHub Issues: For bugs and feature requests
GitHub Discussions: For questions and discussions

Thank you for contributing to TRX-Python!