diff --git a/QUALITY_DECLARATION.md b/QUALITY_DECLARATION.md new file mode 100644 index 0000000..54d9626 --- /dev/null +++ b/QUALITY_DECLARATION.md @@ -0,0 +1,240 @@ +# 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](https://www.ros.org/reps/rep-2004.html). + +## 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](https://semver.org/) as recommended by the +[ROS 2 Developer Guide](https://docs.ros.org/en/jazzy/The-ROS2-Project/Contributing/Developer-Guide-Build-Debs.html). + +All packages in the repository share the same version number. + +### Version Stability [1.ii] + +The current version is **0.2.0** (initial rosdistro release). +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](docs/api/rest.rst) and follows the +[SOVD standard](https://www.asam.net/standards/detail/sovd/) 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](https://github.com/selfpatch/ros2_medkit). +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 + linter tests + unit/integration tests on Ubuntu Noble / ROS 2 Jazzy +- **Coverage job:** Debug build with coverage. Reports are generated for all PRs as artifacts and uploaded to [Codecov](https://codecov.io/gh/selfpatch/ros2_medkit) on pushes to `main` +- Linting enforced: `clang-format`, `clang-tidy` via `ament_lint_auto` + +CI configuration: [`.github/workflows/ci.yml`](.github/workflows/ci.yml) + +### Documentation Policy [2.v] + +Documentation is built and deployed via a separate +[docs workflow](.github/workflows/docs.yml) using Sphinx + Doxygen (Breathe). + +--- + +## Documentation [3] + +### Feature Documentation [3.i] + +Features are documented in the [online documentation](https://selfpatch.github.io/ros2_medkit/) +and the [README.md](README.md). + +### Public API Documentation [3.ii] + +- REST API: [docs/api/rest.rst](docs/api/rest.rst) (700+ lines, all endpoints documented) +- ROS 2 messages/services: [docs/api/messages.rst](docs/api/messages.rst) +- C++ API: [docs/api/cpp.rst](docs/api/cpp.rst) (Doxygen-generated via Breathe) + +### License [3.iii] + +The license for `ros2_medkit` is **Apache License 2.0**. +See the [LICENSE](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](https://codecov.io/gh/selfpatch/ros2_medkit)). + +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** + +This is the primary Tier 1 platform for ROS 2 Jazzy per [REP-2000](https://www.ros.org/reps/rep-2000.html). + +--- + +## Security [7] + +### Vulnerability Disclosure Policy [7.i] + +The project follows the ROS 2 vulnerability disclosure policy as described in +[REP-2006](https://www.ros.org/reps/rep-2006.html). + +Security issues can be reported via GitHub Security Advisories on the +[ros2_medkit repository](https://github.com/selfpatch/ros2_medkit/security). + +--- + +## Current Status Summary + +| Requirement | Status | Notes | +|---|---|---| +| Version policy | Met | Semver, all packages at 0.2.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 | +| Security policy | Met | REP-2006 compliant | + +**Caveat:** Version is 0.2.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. diff --git a/README.md b/README.md index 34b5641..3b4bad5 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) [![ROS 2](https://img.shields.io/badge/ROS%202-Jazzy-blue)](https://docs.ros.org/en/jazzy/) [![Discord](https://img.shields.io/badge/Discord-Join%20Us-7289DA?logo=discord&logoColor=white)](https://discord.gg/6CXPMApAyq) +[![Quality Level 3](https://img.shields.io/badge/Quality-Level%203-yellow)](QUALITY_DECLARATION.md)

Robots break. Now you'll know why.