Contributing to StreamPoseML¶

We’re excited that you’re interested in contributing to StreamPoseML! This guide will help you get started as a contributor.

Ways to Contribute¶

There are many ways to contribute to StreamPoseML:

Code: Fix bugs, implement new features, or improve performance
Documentation: Help improve or translate documentation
Testing: Create tests or report bugs
Examples: Share your use cases or implementation examples
Research: Cite us in your research or suggest new features based on research needs

Getting Started¶

Setting Up Your Development Environment¶

Fork the repository on GitHub

Clone your fork:

git clone https://github.com/YOUR-USERNAME/StreamPoseML.git
cd StreamPoseML

Set up a virtual environment (recommended):

# Create a virtual environment
python -m venv venv

# Activate it (Linux/Mac)
source venv/bin/activate

# Or on Windows
venv\\Scripts\\activate

Install in development mode:

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

# Run setup.py to set paths correctly
python setup.py

Development Workflow¶

We follow the GitHub Flow workflow:

Create a feature branch from main

git checkout main
git pull origin main
git checkout -b feature/your-feature-name

Write your code and tests

Make your changes, following our coding standards (we use Black for formatting). Add or modify tests as needed.

Run tests locally

# Run all tests
make test

# Format your code
make lint

Commit your changes

Use clear, descriptive commit messages that explain what you’ve changed and why.
Submit a pull request
- Push your branch to your fork
- Create a pull request against the main repository’s main branch
- Fill out the pull request template with all relevant information
Address review feedback

Respond to any feedback from maintainers and make necessary changes.
Your PR gets merged!

Coding Standards¶

We use Black for code formatting
Follow Python’s PEP 8 style guide
Write clear docstrings in the NumPy format
Include type hints where appropriate
Update documentation for new features or changes

Testing¶

All new code should include appropriate tests:

Unit tests for individual functions and classes
Integration tests for component interactions
End-to-end tests for complete workflows

Run tests using pytest:

# Run all tests
make test

# Run specific test files
pytest stream_pose_ml/tests/path/to/test_file.py

# Run with coverage
pytest --cov=stream_pose_ml

Documentation¶

Good documentation is crucial for usability:

Update existing docs when changing functionality
Add new documentation for new features
Create examples to demonstrate usage

To build and view the documentation:

# Build docs
make docs

# View in browser
open docs/build/html/index.html

First-time Contributors¶

If this is your first contribution to StreamPoseML:

Look for issues labeled good first issue on our issues page
Introduce yourself in the issue comments and express your interest
A maintainer will help guide you through your first contribution

Need Help?¶

If you have questions or need assistance:

Ask questions in the GitHub issue for your feature
Join our community discussions (if applicable)
Reach out to the maintainers directly

License¶

By contributing to StreamPoseML, you agree that your contributions will be licensed under the project’s MIT License.

StreamPoseML

Navigation

Related Topics