This document is a declaration of software quality for the Eclipse Cyclone DDS (hereafter simply "Cyclone DDS") project, based on the guidelines in REP-2004.
Cyclone DDS meets all the requirements of Quality Level 3 category. The requirements for the various quality level categories are defined by REP-2004. The rationale, notes and caveats for this claim are provided by the remainder of this document.
Cyclone DDS version numbers are organised as MAJOR.MINOR.PATCH where all three components are non-negative decimal numbers. Version number policy follows the following rules:
- MAJOR version is incremented when an incompatible API change is made;
- MINOR version when functionality is added in a backwards compatible manner. MINOR is source compatible, the project strives to also maintain binary compatibility;
- PATCH version when backwards compatible bug fixes are made. PATCH is binary compatible.
On incrementing a number, all numbers to the right of it are reset to 0.
Major version 0 is considered stable.
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format and start at the first character following the PATCH that is not a decimal digit.
See also the Releases section of the Eclipse project handbook which discusses Major, Minor, and Service release criteria (where Service corresponds to PATCH in the above description.
Cyclone DDS is at a stable version. The current version is the highest versioned Git tag that consists of three decimal numbers separated by periods. For each minor release, there exists a releases/MAJOR.MINOR.x branch that is used for PATCH releases.
The change history can be found in the CHANGELOG.
Symbols starting with dds_ or DDS_ and that are accessible after including only the top-level dds.h file, unless explicitly stated otherwise in a documentation comment, constitute the Public API.
Definitions available in installed include files that are outside this definitions are either internal or part of an Evolving API that is expected to eventually become part of the Public API. The distinction between Evolving APIs and internal definitions is currently not well-defined.
In the source repository, these header files reside with the modules that make up Cyclone DDS.
Cyclone DDS provides Public API stability for PATCH and MINOR releases. Cyclone DDS strives to provide Public API stability for MAJOR releases. Cyclone DDS does not guarantee Public API stability for MAJOR releases.
Cyclone DDS provides Evolving API stability for PATCH releases and strives to provide Evolving API stability for MINOR releases. Cyclone DDS does not guarantee Evolving API stability for MINOR and MAJOR releases.
The RMW interface is what ROS 2 deals with, and for a variety of reasons it may be decided to rely on unstable interfaces (or even implementation details), to better support ROS 2's design decisions that do not fit so well with DDS. Given ROS 2's importance to Cyclone DDS the Public API is expected to eventually cover all of ROS 2's needs, but without a defined time-line for that to happen.
The Cyclone DDS projects takes these uses into account, but it may at times even require source changes to the RMW layer. As the Cyclone DDS project is actively involved in maintaining the RMW layer, such cases are handled by scheduling updates and performing additional compatibility checks against the ROS 2 test suite to ensure they do not cause any disruption to ROS 2.
Those changes are all hidden in the interface between the RMW layer and Cyclone DDS itself and are of no concern to ROS 2 applications.
It just means that, in the general case, one should always use a matched pair of rmw_cyclonedds_cpp and cyclonedds.
Cyclone DDS provides ABI stability for PATCH releases and strives to provide ABI stability for MINOR releases, for both Public and Evolving APIs. Cyclone DDS does not guarantee ABI stability for MINOR or MAJOR releases.
ROS 2 users do not interact directly with Cyclone DDS and the mapping of the RMW interface to the Cyclone DDS APIs provided by the rmw_cyclonedds package hides any API or ABI changes from ROS 2 users.
Based on the ABI Stability Policy, Cyclone DDS PATCH releases can be accepted as updates within a Released ROS Distribution without also requiring an update to the rmw_cyclonedds package.
Cyclone DDS MINOR and MAJOR releases can, at least in principle, be accepted as updates within a Released ROS Distribution if the update is accompanied by an update of the rmw_cyclonedds package.
Cyclone DDS follows the recommended guidelines of the Eclipse Development Process.
The Eclipse Foundation manages write access to project repositories, allowing only designated Committers, who have been voted for in elections overseen by the Eclipse Foundation, to commit changes.
API and ABI stability is part of the review process. The Cyclone DDS project runs CI and tests. The Cyclone DDS project runs ROS CI for changes that are likely to affect ROS.
All changes occur through a pull request.
This package uses DCO as its confirmation of contributor origin policy. More information can be found in Eclipse Foundation's DCO policy. Eclipse projects furthermore require that an Eclipse Contributor Agreement is on file with the Eclipse Foundation.
All pull requests must pass peer-review except when no-one is able to provide a review for a PR introduced by a Committer. Check Eclipse Developer Process for additional information.
Pull requests are required to pass all tests in the CI system prior to merging, unless Committers consider there is sufficient evidence that a failure is the result of a mishap unrelated to the change. Cyclone DDS CI results are public and cover x64 platforms running Linux, macOS and Windows 10:
- Ubuntu 18.04 with gcc 10
- Ubuntu 18.04 with clang 10
- macOS 10.15 with Xcode 11.6
- Windows 10 version 1809 with Visual Studio 2017
These are run with a mixture of debug, debug-with-address sanitizer and release builds.
ROS 2 CI also runs the Cyclone DDS tests, which provides further coverage, including the exact platforms used for ROS 2 releases.
All pull requests must resolve related documentation changes before merging.
The project documentation does not include a high-level overview of the features and concepts. These closely follow the OMG DDS specification which provides an accessible description.
Some components can be enabled/disabled at compile-time through compilation options from the CMake files (e.g., DDS Security support). The exact set is not well-documented. Some other features are included/excluded at build time based on the features provided by the target platform (e.g., source-specific multicasting, DNS support to allow hostnames to be used in the configuration). These are also not well-documented.
Reference information for the Public API is provided in the form of Doxygen comments. Configuration settings are documented in the source, with auto-generated XSD files and markdown files committed in the repository and linked from the front page. Background information on configuration settings is also provided.
Generated documentation for the API is available in the PDF document linked in the project README.
The license for Cyclone DDS is the Eclipse Public License 2.0 and the Eclipse Distribution License 1.0, and all of the code includes a header stating so.
The project includes a NOTICE with links to more information about these licenses.
The Cyclone DDS repository also includes a LICENSE file with the full terms.
There is some third-party content included with Cyclone DDS which is licensed as Zlib, New BSD, and Public Domain.
Details can also be found in the included NOTICE document.
The Cyclone DDS documentation includes a policy regarding content copyright, each of the source files containing code include a copyright statement with the license information in the file's header.
Some directories within the Cyclone DDS source tree contain subdirectories for test code. In all, the test code appears to comprise approximately 25% of the codebase.
Each feature in Cyclone DDS has corresponding tests which simulate typical usage, and they are located in separate directories next to the sources. New features are required to have tests before being added.
A substantial amount of the tests found throughout the source tree verify functionality of various features of Cyclone DDS. However the lack of a complete feature list (see section [3.i]) makes it difficult to analyze the breadth of the tests.
Each part of the public API has tests, and new additions or changes to the public API require tests before being added. The tests aim to cover both typical usage and corner cases. There are some tests throughout the Cyclone DDS source tree which specifically target the public API. In principle the entire interface does get tested, and in reality it is pretty close.
Current lack of analysis of which parts of the code get hit by tests do make it hard to measure the extent of the tests.
In continuous integration, address sanitizer is enabled for some of the test matrix. Address sanitizer errors result in CI failure.
Cyclone DDS publishes test coverage using Codecov. New changes are required to include tests coverage. Line coverage is approximately 75% (as of 2020-09-04).
While there are no automated, public tests or results, there is evidence in PRs that performance does get taken into account (see, e.g., https://github.com/eclipse-cyclonedds/cyclonedds#558).
ddsperf is used to check for performance regressions regularly and before releases.
Performance-sensitive PRs are tested for regressions using ddsperf before changes are accepted.
ddsperf is the tool to use for assessing Cyclone DDS performance.
ros2 nightly CI performance tests exist but is not reliable infrastructure. We suggest and would like to assist Open Robotics to move all performance testing to dedicated hardware.
rmw_cyclonedds uses and passes all the ROS2 standard linters and static analysis tools for a C++ package as described in the ROS 2 Developer Guide.
Passing implies there are no linter/static errors when testing against CI of supported platforms.
Cyclone DDS has automated daily Synopsys Coverity static code analysis with public results that can be seen here. Cyclone DDS defect density is 0.05 per 1,000 lines of code as of Aug 11th 2020. Omitting the Java idlc which is not used by ROS 2 gives 0.03 per 1,000 lines of code. For comparison the average defect density of open source software projects of similar size is 0.5 per 1,000 lines of code.
There are no linters enabled for the Cyclone DDS repository.
Coding style is considered and enforced in the review of all Cyclone DDS pull requests. Contributors are regularly asked to rewrite or reformat their code contributions before pull requests are accepted. This is a matter of public record in the Cyclone DDS pull request history.
As an external dependency, there are no ROS dependencies in Cyclone DDS.
As an external dependency, there are no ROS dependencies in Cyclone DDS.
The only runtime dependency of Cyclone DDS is OpenSSL, a widely-used secure communications suite. If Cyclone DDS is built without security enabled, the product has no runtime dependencies.
Cyclone DDS supports all of the tier 1 platforms as described in REP-2000. Cyclone DDS CI test coverage does not exactly match the tier 1 platforms of ROS 2. The ROS 2 CI includes the Cyclone DDS CI tests, and so there is automated validation that all tier 1 platforms are fully supported.
Regarding minimum versions they are basically not known exactly because Cyclone DDS builds and runs on everything that was tested including ancient versions of Linux and macOS. For evidence, the fact that Cyclone DDS builds and runs on Solaris 2.6 on SPARCv8 (given pre-generated header files and IDL output) is a fair indication of its broad support of platforms and old versions.
The README specifies mininum versions that are new enough.
This package conforms to the Vulnerability Disclosure Policy in REP-2006. The Eclipse Project Handbook states the project's vulnerability disclosure policy in detail.