Contributing

We welcome contributions to SlicerMouseMaster! This guide explains how to contribute effectively.

Ways to Contribute

  • Bug reports: File issues for problems you encounter

  • Feature requests: Suggest new functionality

  • Code contributions: Submit pull requests

  • Documentation: Improve guides and examples

  • Presets: Share your button configurations

  • Mouse profiles: Add support for new mice

Development Setup

  1. Fork the repository on GitHub

  2. Clone your fork:

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

  3. Set up development environment:

    uv sync
uv run pre-commit install

  4. Create a feature branch:

    git checkout -b feature/your-feature-name

Code Style

We use automated tools to maintain consistent code style:

  • Ruff: Linting and formatting

  • Mypy: Type checking

Run checks before committing:

make lint       # Run linter
make format     # Format code
make typecheck  # Run type checker
make check      # Run lint and typecheck together

Pre-commit hooks run these automatically.

Commit Messages

Follow conventional commit format:

<type>: <short summary>

[optional body with details]

[optional footer with references]

Types:

  • feat: New feature

  • fix: Bug fix

  • docs: Documentation only

  • refactor: Code change that neither fixes a bug nor adds a feature

  • test: Adding or updating tests

  • chore: Maintenance tasks

Examples:

feat: add MX Master 4 support

- Add mouse definition JSON
- Create default preset
- Update supported mice documentation

Closes #42

fix: handle missing preset file gracefully

Previously the module would crash if a preset file was deleted
while MouseMaster was running. Now it shows an error message
and falls back to the default preset.

Pull Requests

  1. Keep PRs focused: One feature or fix per PR

  2. Update documentation: Add or update docs for your changes

  3. Add tests: Include unit tests for new functionality

  4. Run the test suite: Ensure all tests pass

  5. Write a clear description: Explain what and why

PR Template:

## Summary

Brief description of changes.

## Changes

- Change 1
- Change 2

## Testing

- [ ] Unit tests pass
- [ ] Manual testing completed
- [ ] Documentation updated

## Related Issues

Closes #123

Reporting Bugs

Good bug reports include:

  1. Slicer version: Help > About 3D Slicer

  2. Operating system: Windows/macOS/Linux and version

  3. Mouse model: The mouse you’re using

  4. Steps to reproduce: Detailed steps to trigger the bug

  5. Expected behavior: What should happen

  6. Actual behavior: What actually happens

  7. Error messages: From Python console (View > Python Console)

  8. Screenshots: If applicable

Feature Requests

When requesting features:

  1. Check existing issues: Someone may have already requested it

  2. Describe the use case: Why do you need this?

  3. Suggest implementation: If you have ideas

  4. Be open to discussion: The best solution may differ from your initial idea

Contributing Presets

Share your button configurations:

  1. Export your preset from MouseMaster

  2. Add author and description to the JSON

  3. Submit via:

    • GitHub issue with the file attached

    • Pull request to presets/community/

See Preset Format for preset format details.

Contributing Mouse Profiles

Add support for new mice:

  1. Create mouse definition JSON

  2. Create default preset

  3. Test on your hardware

  4. Submit pull request

See Adding Mouse Profiles for detailed instructions.

Code of Conduct

Getting Help

  • Questions: Open a GitHub Discussion

  • Chat: Join the Slicer Discord

  • Forum: Post on Slicer Discourse

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.