Skip to content

QUALITY_DECLARATION.md

Latest commit

 

History

History
242 lines (156 loc) · 8.58 KB

QUALITY_DECLARATION.md

File metadata and controls

242 lines (156 loc) · 8.58 KB

Quality Declaration for ros2_medkit

This document is a declaration of software quality for the ros2_medkit packages, based on the guidelines in REP-2004.

Quality Level 3

This repository (ros2_medkit, 6 packages) claims to be in the Quality Level 3 category.

The packages covered by this declaration:

Package Description
ros2_medkit_fault_manager Central fault management node with storage, correlation, and rosbag capture
ros2_medkit_gateway REST API gateway (SOVD-compatible) with SSE, auth, and discovery
ros2_medkit_msgs Custom message and service definitions
ros2_medkit_fault_reporter Client library for fault reporting
ros2_medkit_serialization Runtime JSON serialization for ROS 2 messages
ros2_medkit_diagnostic_bridge Bridge node converting /diagnostics to medkit faults

Below is the rationale, organized by each requirement listed in REP-2004.

Version Policy [1]

Version Scheme [1.i]

ros2_medkit uses Semantic Versioning 2.0.0 as recommended by the ROS 2 Developer Guide.

All packages in the repository share the same version number.

Version Stability [1.ii]

The current version is 0.3.0. The package follows semver; the pre-1.0 version reflects that the public API may still evolve based on early adopter feedback, not a lack of quality infrastructure. The 1.0.0 release is planned after the API has been validated through pilot deployments.

Public API Declaration [1.iii]

Public API headers are organized in include/ directories for each package:

  • ros2_medkit_fault_reporter/include/ — fault_reporter.hpp, local_filter.hpp
  • ros2_medkit_serialization/include/ — json_serializer.hpp, type_cache.hpp
  • ros2_medkit_fault_manager/include/ — fault_manager_node.hpp, fault_storage.hpp
  • ros2_medkit_gateway/include/ — gateway_node.hpp, data_access_manager.hpp, operation_manager.hpp

The REST API is documented at docs/api/rest.rst and follows the SOVD standard for endpoint structure.

ROS 2 message and service definitions in ros2_medkit_msgs constitute a stable public interface.

API Stability Within a Released ROS Distribution [1.iv]

API stability is a goal but not yet formally guaranteed (pre-1.0.0). Breaking changes, if any, are documented in package-level CHANGELOG.rst files. The REST API is versioned (/api/v1/) and follows the SOVD standard, providing de facto stability.

ABI Stability Within a Released ROS Distribution [1.vi]

ABI stability is not guaranteed at this time. This is not required for Quality Level 3.

Change Control Process [2]

All Changes via Change Request [2.i]

All changes to ros2_medkit occur through pull requests on GitHub. The main branch is protected; direct pushes are not allowed.

Contributor Origin [2.ii]

Contributor origin is tracked via Git commit history and GitHub accounts. Contributions are accepted under the repository's Apache-2.0 license.

Peer Review Policy [2.iii]

All pull requests require at least one approving review before merge. GitHub Copilot code review is used in addition to human review.

Continuous Integration [2.iv]

All pull requests must pass CI before merging:

  • Build & Test job: Full build + unit/integration tests on Ubuntu Noble / ROS 2 Jazzy, Ubuntu Jammy / ROS 2 Humble, and Ubuntu Noble / ROS 2 Rolling (best-effort, allow-failure). Linter tests on Jazzy only
  • Coverage job: Debug build with coverage. Reports are generated for all PRs as artifacts and uploaded to Codecov on pushes to main
  • Linting enforced: clang-format, clang-tidy via ament_lint_auto

CI configuration: .github/workflows/ci.yml

Documentation Policy [2.v]

Documentation is built and deployed via a separate docs workflow using Sphinx + Doxygen (Breathe).

Documentation [3]

Feature Documentation [3.i]

Features are documented in the online documentation and the README.md.

Public API Documentation [3.ii]

License [3.iii]

The license for ros2_medkit is Apache License 2.0. See the LICENSE file. Each source file contains the license header.

Copyright Statements [3.iv]

Copyright is held by selfpatch.ai (Bartosz Burda, Michal Faferek). Copyright statements are included in all source files.

Quality Declaration [3.v]

This is the quality declaration document (you are reading it).

Testing [4]

Feature Testing [4.i]

The test suite comprises:

Category Count Lines of Test Code
C++ unit tests (GTest) 52 ~14,000
Python integration tests (launch_testing) 13 ~3,000

Tests cover: fault management, storage backends (SQLite + in-memory), snapshot capture, rosbag capture, correlation engine, REST API endpoints, authentication, discovery, configuration management, JSON serialization, and diagnostic bridge.

Public API Testing [4.ii]

All REST API endpoints are covered by integration tests. All ROS 2 service interfaces are covered by unit tests.

Coverage [4.iii]

Current line coverage: 75% (as reported by Codecov).

Coverage is generated in CI and uploaded to Codecov for main branch builds, with a 1% regression threshold configured in codecov.yml. Test directories, demo nodes, and build artifacts are excluded from coverage measurement.

Performance Testing [4.iv]

No dedicated performance regression tests at this time.

Linters and Static Analysis [4.v]

All packages use:

  • ament_cmake_clang_format — code formatting
  • ament_cmake_clang_tidy — static analysis
  • ament_lint_auto + ament_lint_common — standard ROS 2 linting

Linter tests are enforced in CI on every pull request.

Dependencies [5]

Direct Runtime ROS Dependencies [5.i]

Dependency Quality Level
rclcpp Level 1
builtin_interfaces Level 1
diagnostic_msgs Level 1
rosbag2_cpp Level 3
rosbag2_storage Level 3

Optional Direct Runtime Non-ROS Dependencies [5.ii]

Dependency Description
sqlite3 Fault storage backend
nlohmann-json JSON parsing
cpp-httplib HTTP server (header-only)
libssl TLS support
jwt-cpp JWT authentication (vendored, header-only)

Platform Support [6]

Target Platforms [6.i]

ros2_medkit is tested and supported on:

  • Ubuntu 24.04 (Noble) with ROS 2 Jazzy (primary)
  • Ubuntu 22.04 (Jammy) with ROS 2 Humble
  • Ubuntu 24.04 (Noble) with ROS 2 Rolling (experimental, best-effort)

Jazzy and Humble are the Tier 1 platforms per REP-2000 and are tested in CI. Rolling is tested as best-effort (allow-failure) for forward-compatibility.

Security [7]

Vulnerability Disclosure Policy [7.i]

The project follows the ROS 2 vulnerability disclosure policy as described in REP-2006.

Security issues can be reported via GitHub Security Advisories on the ros2_medkit repository.

Current Status Summary

Requirement Status Notes
Version policy Met Semver, all packages at 0.3.0
Stable version (>=1.0.0) Caveat Pre-1.0; API versioned, 1.0.0 planned post-pilot
Change requests Met All changes via PR
CI Met Build + test + coverage on every PR
License Met Apache-2.0
Copyright Met All source files have headers
Feature tests Met 65 tests across unit + integration
Coverage Met 75% line coverage
Linting Met clang-format, clang-tidy, ament_lint
Platform support Met Ubuntu Noble / ROS 2 Jazzy + Ubuntu Jammy / ROS 2 Humble + Rolling (best-effort)
Security policy Met REP-2006 compliant

Caveat: Version is 0.3.0 (pre-1.0.0, requirement 1.ii). The REST API is versioned (/api/v1/) and the package meets all other Level 3 requirements. The 1.0.0 release is planned after API validation through pilot deployments.