Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
155 lines (113 loc) · 5.95 KB

CONTRIBUTING.md

File metadata and controls

155 lines (113 loc) · 5.95 KB

Contributing to ros2_medkit

Thanks for your interest in contributing to ros2_medkit! This guide explains how to report issues, suggest features, and contribute code.

How to Report Issues

Did you find a bug?

  • Ensure the bug was not already reported by searching Issues
  • If you can't find an existing issue, open a new one and select the Bug report template
  • Fill in all sections of the template:
    • Steps to reproduce - numbered steps to recreate the issue
    • Expected behavior - what you expected to happen
    • Actual behavior - what actually happened, including error messages or stack traces
    • Environment - ros2_medkit version, ROS 2 distro, OS
    • Additional information - logs, snippets, or screenshots if helpful

Do you want to suggest a feature or improvement?

  • Check if the feature has already been suggested in Issues
  • If not, open a new issue and select the Feature request / General issue template
  • Fill in all sections:
    • Proposal - describe the change or feature you'd like to see
    • Motivation - why is this important? Who does it benefit?
    • Alternatives considered - other options or implementations you considered
    • Additional context - any other context or screenshots

How to Contribute Code

Development Workflow

  1. Fork the repository and clone your fork locally
  2. Install pre-commit hooks (one-time setup): 
    pip install pre-commit
pre-commit install
  3. Create a branch from main with a descriptive name:
    • feature/short-description for new features
    • fix/short-description for bug fixes
    • docs/short-description for documentation changes
  4. Make your changes following the project's coding standards
  5. Test your changes locally (see Build and Test section below)
  6. Commit your changes with clear, descriptive commit messages
    • Pre-commit hooks will automatically check formatting
  7. Push your branch to your fork
  8. Open a Pull Request against the main branch of this repository

Commit Messages

  • Use clear and descriptive commit messages
  • Start with a verb in imperative mood (e.g., "Add", "Fix", "Update", "Remove")
  • Keep the first line under 72 characters
  • Add a blank line followed by a more detailed explanation if needed

Examples:

Add support for SOVD entity mapping

Fix memory leak in diagnostic tree traversal

Update documentation for colcon build process

Build and Test

Before opening or updating a Pull Request, you must build and test locally:

source /opt/ros/jazzy/setup.bash   # or humble - adjust for your distro
rosdep install --from-paths src --ignore-src -r -y
colcon build --symlink-install && source install/setup.bash

Use scripts/test.sh for testing (preferred over raw colcon commands):

./scripts/test.sh              # Unit tests only (default)
./scripts/test.sh integ        # Integration tests only
./scripts/test.sh lint         # Fast linters (no clang-tidy)
./scripts/test.sh all          # Everything
./scripts/test.sh <test_name>  # Single test by CTest name regex

Pre-commit and Pre-push Hooks

pipx install pre-commit
pre-commit install
pre-commit install --hook-type pre-push

On commit: clang-format, cmake-lint, shellcheck, flake8, ament-copyright, trailing whitespace. On push: incremental clang-tidy on changed .cpp files.

Code Coverage

colcon build --cmake-args -DCMAKE_BUILD_TYPE=Debug -DENABLE_COVERAGE=ON
./scripts/test.sh              # run tests
lcov --capture --directory build --output-file coverage.raw.info --ignore-errors mismatch,negative
lcov --extract coverage.raw.info '*/ros2_medkit/src/*/src/*' '*/ros2_medkit/src/*/include/*' --output-file coverage.info
genhtml coverage.info --output-directory coverage_html

Open coverage_html/index.html in your browser.

CI/CD

All PRs are tested on Ubuntu 24.04 (Jazzy) with parallel lint + test jobs, plus Humble and Rolling (allowed to fail). Coverage is uploaded to Codecov on push to main. All CI jobs use ccache.

Pull Request Checklist

Before submitting your PR, ensure:

  • Code follows the repository's style and conventions
  • Build succeeds without warnings
  • All tests pass locally
  • New tests are added for new functionality
  • Existing tests are updated if behavior changes
  • Documentation is updated where applicable
  • PR description clearly explains what changed and why
  • Related issue is referenced (e.g., "Fixes #123")

Code Review Process

  • The project maintainers will review pull requests as time permits
  • Address review feedback promptly
  • Keep discussions professional and constructive
  • Be patient - maintainers may need time to review

What NOT to Contribute

  • Purely cosmetic changes that don't add functionality (whitespace, formatting without other changes)
  • Large refactors without prior discussion - open an issue first
  • Breaking changes without coordination with maintainers
  • Code that doesn't pass tests or breaks existing functionality

Questions and Help

  • For questions about using ros2_medkit, open a Discussion or an Issue with the question label
  • For questions about contributing, feel free to ask in your PR or Issue
  • For security vulnerabilities, see SECURITY.md

Code of Conduct

By contributing to ros2_medkit, you agree to abide by our Code of Conduct. Please be respectful and considerate in all interactions.

License

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

Thank you for improving ros2_medkit! We value contributions of all sizes - from typo fixes to major features. 🚀