Contributing

RosFit is an open-source project and we welcome contributions of all kinds — bug fixes, new features, device compatibility reports, documentation improvements, and community guides.

Repository structure

The RosFit monorepo is organized into the following top-level directories:

rosfit/
├── api/                  # FastAPI backend (Python)
│   ├── app/
│   │   ├── routers/      # API route handlers
│   │   ├── models/       # SQLAlchemy / Pydantic models
│   │   ├── services/     # Business logic
│   │   └── core/         # Config, security, dependencies
│   ├── tests/
│   └── requirements.txt
├── bridge/               # ROS 2 ↔ MQTT bridge (Python, rclpy)
│   ├── rosfit_bridge/
│   ├── tests/
│   └── setup.py
├── handler/              # MQTT message consumer (Python)
│   ├── handler/
│   ├── tests/
│   └── requirements.txt
├── dashboard/            # React frontend (TypeScript, Vite)
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── hooks/
│   │   └── lib/
│   ├── tests/
│   └── package.json
├── sdk/                  # Client SDKs
│   ├── typescript/       # @rosfit/sdk (npm)
│   └── python/           # rosfit (PyPI)
├── cli/                  # rosfit-cli (Python)
├── docs/                 # This documentation site (Next.js, MDX)
├── docker/               # Dockerfiles for each service
├── deploy/               # Kubernetes manifests, Helm chart
├── grafana/              # Grafana dashboard templates
├── docker-compose.yml    # Local development stack
├── .env.example          # Environment variable template
└── README.md

How to contribute

Report bugs and request features

Open an issue on GitHub Issues with one of the provided templates:

• Bug report — describe the issue, steps to reproduce, expected vs actual behavior, and your environment (OS, ROS 2 distro, Docker version)
• Feature request — describe the use case, proposed solution, and alternatives considered
• Device compatibility report — share your experience connecting a new robot, MCU, or broker to RosFit

Submit pull requests

1. Fork the repository and create a feature branch:

git clone https://github.com/<your-username>/rosfit.git
cd rosfit
git checkout -b feat/my-new-feature

2. Make your changes following the code style guidelines below.

3. Write tests for any new functionality.

4. Run the test suite locally:

# API tests
cd api && pytest tests/ -v

# Bridge tests
cd bridge && pytest tests/ -v

# Dashboard tests
cd dashboard && npm test

# Integration tests (requires Docker)
docker compose -f docker-compose.test.yml up -d
pytest tests/integration/ -v

5. Submit the PR against the main branch. Fill out the PR template with:
   • Summary of changes
   • Related issue number
   • Test plan
   • Screenshots (for UI changes)

Device compatibility reports

Tried RosFit with hardware that isn't mentioned in the docs? We want to hear about it. Open an issue with the "Device Compatibility" template and include:

• Hardware model and specifications
• ROS 2 distro and version
• Bridge configuration used
• Any issues encountered and workarounds
• Performance observations (latency, throughput)

Successful compatibility reports are added to the documentation.

Code style and testing

Python (API, Bridge, Handler, CLI)

# Run all Python checks
ruff format --check .
ruff check .
mypy api/ bridge/ handler/ cli/
pytest --cov --cov-report=term-missing

TypeScript (Dashboard, SDK)

# Run all TypeScript checks
cd dashboard
npm run lint
npm run typecheck
npm run test -- --coverage

Commit messages

Follow Conventional Commits:

feat(bridge): add throttle_hz support for publish topics
fix(api): correct shadow version conflict handling
docs(guides): add ESP32-CAM security camera guide
test(handler): add telemetry ingestion benchmarks
chore(docker): upgrade EMQX to 5.5

Prefix with the component in parentheses: api, bridge, handler, dashboard, sdk, cli, docs, docker, deploy.

Documentation contributions

The documentation site lives in docs/ and is built with Next.js and MDX. To run it locally:

cd docs
npm install
npm run dev

The site is available at http://localhost:3000.

Writing guides

Each documentation page is an MDX file at docs/src/app/<slug>/page.mdx. Follow the existing format:

1. Export metadata with title and description
2. Export sections array with title and id for each heading
3. Start with an H1 heading matching the title
4. Add {{ className: 'lead' }} after the first paragraph
5. Use markdown headings, code blocks, and tables
6. End with a navigation button linking to the next logical page

Adding a new page

1. Create the directory: mkdir docs/src/app/<slug>
2. Create the file: docs/src/app/<slug>/page.mdx
3. Add the page to the navigation in docs/src/components/Navigation.tsx
4. Submit a PR

Roadmap

RosFit is under active development. Here are the planned features for upcoming releases:

Want to work on one of these? Check the GitHub Issues for related discussions and draft PRs. We are happy to mentor first-time contributors.