Contributing¶

Welcome! We’re excited you’re interested in contributing to ProtoMotions.

This project thrives on community involvement. Whether you’re fixing a typo, adding a feature, or sharing your research—every contribution matters.

Ways to Contribute¶

There are many ways to help, and you don’t need to be an expert:

Share Your Work: Used ProtoMotions in a project or paper? Let us know! We’d love to feature it.
Report Issues: Found a bug? Something confusing in the docs? Open an issue and tell us about it.
Improve Documentation: Spotted a typo? Have a better explanation for something? Documentation improvements are always welcome.
Add Examples: Created a cool experiment configuration or training setup? Share it with others.
Fix Bugs: Browse open issues and pick one that interests you.
Add Features: Have an idea for a new feature? Open an issue to discuss it first, then submit a PR.

Getting Started¶

Fork the repository on GitHub

Clone your fork:

git clone https://github.com/YOUR_USERNAME/ProtoMotions.git
cd ProtoMotions

Create a branch for your changes:
```
git checkout -b my-contribution
```
Make your changes and test them
Commit with a clear message (and sign-off):
```
git commit -s -m "Add feature X"
```
Push to your fork:
```
git push origin my-contribution
```
Open a Pull Request on GitHub

That’s it! We’ll review your PR and work with you to get it merged.

Signing Your Commits¶

We require that all contributors “sign-off” on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license.

To sign off on a commit, use the --signoff (or -s) option:

git commit -s -m "Add cool feature"

This appends the following to your commit message:

Signed-off-by: Your Name <your@email.com>

Note: Any contribution which contains commits that are not signed-off will not be accepted.

Code Style¶

We use pre-commit to automatically format and lint code. To set it up:

pip install pre-commit
pre-commit install

This will run the following checks on every commit:

Ruff for linting and formatting (replaces black, isort, flake8)
Typos for spell checking
License header insertion
Trailing whitespace and end-of-file fixes

You can also run the checks manually:

pre-commit run --all-files

Beyond automated formatting:

Use meaningful variable and function names
Add docstrings to new functions and classes
Keep commits focused—one logical change per commit

Don’t worry about being perfect. We’re happy to help you polish your contribution during review.

Pull Request Tips¶

Keep PRs focused: One feature or fix per PR is easier to review
Describe your changes: Help reviewers understand what you did and why
Test your changes: Make sure things work before submitting
Be patient: We’ll get to your PR as soon as we can

Questions?¶

Not sure where to start? Have questions about the codebase?

Open a GitHub Discussion
Check existing issues for similar questions
Reach out in your PR if you get stuck

We’re here to help. Don’t hesitate to ask!

Thank You¶

Every contribution—big or small—helps make ProtoMotions better for everyone. Thank you for being part of this project!