From c12c755ae11b59480f7d37e6ffe75ee988fdd504 Mon Sep 17 00:00:00 2001 From: William Woodall Date: Fri, 31 Jan 2020 16:53:26 -0800 Subject: [PATCH 1/7] initial draft of the quality declaration Signed-off-by: William Woodall --- README.md | 21 +++- rcl/QUALITY_DECLARATION.md | 203 +++++++++++++++++++++++++++++++++++++ 2 files changed, 223 insertions(+), 1 deletion(-) create mode 100644 rcl/QUALITY_DECLARATION.md diff --git a/README.md b/README.md index b50707d3d..aad6f95b1 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,21 @@ -# rcl +This repository contains several packages which are all related to the `rcl` package. + +### Packages + +#### rcl + Library to support implementation of language specific ROS Client Libraries. + +This package claims to be in the **Quality Level 1** category, see the [Quality Declaration](./rcl/QUALITY_DECLARATION.md) for more details. + +#### rcl_action + +Package containing a C-based ROS action implementation. + +#### rcl_lifecycle + +Package containing a C-based lifecycle implementation. + +#### rcl_yaml_parm_parser + +Package containing various utility types and functions for C. diff --git a/rcl/QUALITY_DECLARATION.md b/rcl/QUALITY_DECLARATION.md new file mode 100644 index 000000000..f61daf8f3 --- /dev/null +++ b/rcl/QUALITY_DECLARATION.md @@ -0,0 +1,203 @@ +This document is a declaration of software quality for the `rcl` package, based on the guidelines in [REP-2004](https://www.ros.org/reps/rep-2004.html). + +# `rcl` Quality Declaration + +The package `rcl` claims to be in the **Quality Level 1** category. + +Below are the rationales, notes, and caveats for this claim, organized by each requirement listed in the [Package Requirements for Quality Level 1 in REP-2004](https://www.ros.org/reps/rep-2004.html). + +## Version Policy + +### Version Scheme + +`rcl` uses `semver` according to the recommendation for ROS Core packages in the [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#versioning), and is at or above a stable version, i.e. `>= 1.0.0`. + +### API Stability Within a Released ROS Distribution + +`rcl` will not break public API within a released ROS distribution, i.e. no major releases once the ROS distribution is released. + +### ABI Stability Within a Released ROS Distribution + +`rcl` contains C code and therefore must be concerned with ABI stability, and will maintain ABI stability within a ROS distribution. + +### Public API Declaration + +All symbols in the installed headers are considered part of the public API. + +All installed headers are in the `include` directory of the package, headers in any other folders are not installed and considered private. + +## Change Control Process + +TODO fix link + +`rcl` follows the recommended guidelines for ROS Core packages in the [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#change_control_process). + +This includes: + +- all changes occur through a pull request +- all pull request have two peer reviews +- all pull request must pass CI on all [tier 1 platforms](https://www.ros.org/reps/rep-2000.html#support-tiers) +- all pull request must resolve related documentation changes before merging + +## Documentation + +### Feature Documentation + +TODO fix link + +`rcl` has a [feature list](TODO) and each item in the list links to the corresponding feature documentation. +There is documentation for all of the features, and new features require documentation before being added. + +### Public API Documentation + +TODO fix link + +`rcl` has embedded API documentation and it is generated using doxygen and is [hosted](TODO) along side the feature documentation. +There is documentation for all of the public API, and new additions to the public API require documentation before being added. + +### License + +The license for `rcl` is Apache 2.0, and a summary is in each source file, the type is declared in the `package.xml` manifest file, and a full copy of the license is in the `LICENSE` file. + +There is an automated test which runs a linter that ensures each file has a license statement. + +### Copyright Statements + +The copyright holders each provide a statement of copyright in each source code file in `rcl`. + +There is an automated test which runs a linter that ensures each file has at least one copyright statement. + +## Testing + +### Feature Testing + +Each feature in `rcl` has corresponding tests which simulate typical usage, and they are located in the `test` directory. +New features are required to have tests before being added. + +### Public API Testing + +Each part of the public API have 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, but are quantified by contributing to code coverage. + +### Coverage + +TODO fix link + +`rcl` follows the recommendations for ROS Core packages in the [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#coverage), and opts to use branch coverage instead of line coverage. + +This includes: + +- tracking and reporting branch coverage statistics +- achieving and maintaining branch coverage at or above 95% +- no lines are manually skipped in coverage calculations + +Changes are required to make a best effort to keep or increase coverage before being accepted, but decreases are allowed if properly justified and accepted by reviewers. + +Current coverage statistics can be viewed here: + +TODO FIXME + +### Performance + +TODO fix link + +`rcl` follows the recommendations for performance testing of C code in the [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#performance-c), and opts to do performance analysis on each release rather than each change. + +TODO how to run perf tests, where do they live, etc. + +TODO exclusions of parts of the code from perf testing listed here? or linked to? + +### Linters and Static Analysis + +TODO fix link + +`rcl` uses and passes all the standard linters and static analysis tools for a C package as described in the [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#linters-and-static-analysis). + +TODO any qualifications on what "passing" means for certain linters + +## Dependencies + +Below are evaluations of each of `rcl`'s run-time and build-time dependencies that have been determined to influence the quality. + +It has several "buildtool" dependencies, which do not affect the resulting quality of the package, because they do not contribute to the public library API. +It also has several test dependencies, which do not affect the resulting quality of the package, because they are only used to build and run the test code. + +### `rmw` + +TODO fix link + +The `rmw` package provides the API used by `rcl` to interact with the underlying middleware in an abstract way. + +It is **Quality Level 1**, see its [Quality Declaration document](FIX). + +### `rcl_interfaces` + +TODO fix link + +The `rcl_interfaces` package provides some common ROS Message and ROS Service types which are used to implement certain client library features. + +It is **Quality Level 1**, see its [Quality Declaration document](FIX). + +### `rcl_logging_spdlog` + +TODO fix link +TODO should this direct dependency be here? + +The `rcl_logging_spdlog` package provides the default logging implementation by wrapping the `spdlog` library. + +It is **Quality Level 1**, see its [Quality Declaration document](FIX). + +### `rcl_yaml_param_parser` + +TODO fix link + +The `rcl_yaml_param_parser` package provides an API that is used to parse YAML configuration files which may be used to configure ROS and specific nodes. + +It is **Quality Level 1**, see its [Quality Declaration document](FIX). + +### `rcutils` + +TODO fix link + +The `rcutils` package provides an API which contains common utilities and data structures needed when programming in C. + +It is **Quality Level 1**, see its [Quality Declaration document](FIX). + +### `rmw_implementation` + +TODO fix link + +The `rmw_implementation` package provides access to the default rmw implementation, and provides the ability to dynamically switch rmw implementations if more than one is available. + +It is **Quality Level 1**, see its [Quality Declaration document](FIX). + +### `rosidl_generator_c` + +TODO fix link + +The `rosidl_generator_c` package provides templates for generating data structures in C based on user defined ROS Messages and ROS Services, as well as associated support functions for those types. +`rcl` uses this pacakge because it uses the C instances of these user defined types in some cases, in combination with the types defined in the `rcl_interfaces` package. + +It is **Quality Level 1**, see its [Quality Declaration document](FIX). + +### `tinydir_vendor` + +TODO fix link + +The `tinydir_vendor` package wraps the third-party library called `tinydir`, which itself provides some basic filesystem operations. + +It is **Quality Level 1**, see its [Quality Declaration document](FIX). + +### `tracetools` + +TODO fix link + +The `tracetools` package provides utilities for instrumenting the code in `rcl` so that it may be traced for debugging and performance analysis. + +It is **Quality Level 1**, see its [Quality Declaration document](FIX). + +## Platform Support + +`rcl` supports all of the tier 1 platforms as described in [REP-2000](https://www.ros.org/reps/rep-2000.html#support-tiers), and tests each change against all of them. + +TODO make additional statements about non-tier 1 platforms? From 8838ad3599f0f264b5a4056f84ad85fa1fdc0058 Mon Sep 17 00:00:00 2001 From: Jorge Perez Date: Fri, 1 May 2020 14:31:00 -0300 Subject: [PATCH 2/7] Reformat to match REP-2004 template Signed-off-by: Jorge Perez --- rcl/QUALITY_DECLARATION.md | 240 ++++++++++++++++++++++--------------- 1 file changed, 143 insertions(+), 97 deletions(-) diff --git a/rcl/QUALITY_DECLARATION.md b/rcl/QUALITY_DECLARATION.md index f61daf8f3..5cab08a84 100644 --- a/rcl/QUALITY_DECLARATION.md +++ b/rcl/QUALITY_DECLARATION.md @@ -2,202 +2,248 @@ This document is a declaration of software quality for the `rcl` package, based # `rcl` Quality Declaration -The package `rcl` claims to be in the **Quality Level 1** category. +The package `rcl` claims to be in the **Quality Level 4** category. -Below are the rationales, notes, and caveats for this claim, organized by each requirement listed in the [Package Requirements for Quality Level 1 in REP-2004](https://www.ros.org/reps/rep-2004.html). +Below are the rationales, notes, and caveats for this claim, organized by each requirement listed in the [Package Quality Categories in REP-2004](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#package-quality-categories). -## Version Policy +## Version Policy [1] -### Version Scheme +### Version Scheme [1.i] -`rcl` uses `semver` according to the recommendation for ROS Core packages in the [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#versioning), and is at or above a stable version, i.e. `>= 1.0.0`. +`rcl` uses `semver` according to the recommendation for ROS Core packages in the [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#versioning). -### API Stability Within a Released ROS Distribution +### Version Stability [1.ii] -`rcl` will not break public API within a released ROS distribution, i.e. no major releases once the ROS distribution is released. +`rcl` is not at a stable version, i.e. `>= 1.0.0`. -### ABI Stability Within a Released ROS Distribution +### Public API Declaration [1.iii] -`rcl` contains C code and therefore must be concerned with ABI stability, and will maintain ABI stability within a ROS distribution. +All symbols in the installed headers are considered part of the public API. -### Public API Declaration +All installed headers are in the [`include`](./include/rcl) directory of the package, headers in any other folders are not installed and considered private. -All symbols in the installed headers are considered part of the public API. +### API Stability Policy [1.iv] -All installed headers are in the `include` directory of the package, headers in any other folders are not installed and considered private. +`rcl` will not break public API within a released ROS distribution, i.e. no major releases once the ROS distribution is released. -## Change Control Process +### ABI Stability Policy [1.v] -TODO fix link +`rcl` contains C++ code and therefore must be concerned with ABI stability, and will maintain ABI stability within a ROS distribution. -`rcl` follows the recommended guidelines for ROS Core packages in the [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#change_control_process). +### ABI and ABI Stability Within a Released ROS Distribution [1.vi] -This includes: +`rcl` will not break API nor ABI within a released ROS distribution, i.e. no major releases once the ROS distribution is released. + +## Change Control Process [2] + +### Change Requests [2.i] + +All changes will occur through a pull request, check the [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#change-control-process) for additional information. + +### Contributor Origin [2.ii] + +This package uses DCO as its confirmation of contributor origin policy. More information can be found in [CONTRIBUTING](../CONTRIBUTING.md). -- all changes occur through a pull request -- all pull request have two peer reviews -- all pull request must pass CI on all [tier 1 platforms](https://www.ros.org/reps/rep-2000.html#support-tiers) -- all pull request must resolve related documentation changes before merging +### Peer Review Policy [2.iii] -## Documentation +All pull request will be peer-reviewed, check [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#change-control-process) for additional information. -### Feature Documentation +### Continuous Integration [2.iv] -TODO fix link +All pull request must pass CI on all [tier 1 platforms](https://www.ros.org/reps/rep-2000.html#support-tiers). -`rcl` has a [feature list](TODO) and each item in the list links to the corresponding feature documentation. -There is documentation for all of the features, and new features require documentation before being added. +Currently nightly results can be seen here: +* [linux-aarch64_release](https://ci.ros2.org/view/nightly/job/nightly_linux-aarch64_release/lastBuild/testReport/rcl/) +* [linux_release](https://ci.ros2.org/view/nightly/job/nightly_linux_release/lastBuild/testReport/rcl/) +* [mac_osx_release](https://ci.ros2.org/view/nightly/job/nightly_osx_release/lastBuild/testReport/rcl/) +* [windows_release](https://ci.ros2.org/view/nightly/job/nightly_win_rel/lastBuild/testReport/rcl/) -### Public API Documentation +### Documentation Policy [2.v] -TODO fix link +All pull requests must resolve related documentation changes before merging. -`rcl` has embedded API documentation and it is generated using doxygen and is [hosted](TODO) along side the feature documentation. -There is documentation for all of the public API, and new additions to the public API require documentation before being added. +## Documentation [3] -### License +### Feature Documentation [3.i] -The license for `rcl` is Apache 2.0, and a summary is in each source file, the type is declared in the `package.xml` manifest file, and a full copy of the license is in the `LICENSE` file. +`rcl` does not have a documented feature list. -There is an automated test which runs a linter that ensures each file has a license statement. +### Public API Documentation [3.ii] -### Copyright Statements +`rcl` has embedded API documentation and it is generated using doxygen. Currently, its eloquent version is hosted [here](http://docs.ros2.org/eloquent/api/rcl/). Latest version has to be generated before considering this item fully resolved. + +New additions to the public API require documentation before being added. + +### License [3.iii] + +The license for `rcl` is Apache 2.0, and a summary is in each source file, the type is declared in the [`package.xml`](./package.xml) manifest file, and a full copy of the license is in the [`LICENSE`](../LICENSE) file. + +There is an automated test which runs a linter that ensures each file has a license statement. [Here](https://ci.ros2.org/view/nightly/job/nightly_linux_release/lastBuild/testReport/rcl/) can be found a list with the latest results of the various linters being run on the package. + +### Copyright Statements [3.iv] The copyright holders each provide a statement of copyright in each source code file in `rcl`. -There is an automated test which runs a linter that ensures each file has at least one copyright statement. +There is an automated test which runs a linter that ensures each file has at least one copyright statement. Latest linter result report can be seen [Here](https://ci.ros2.org/view/nightly/job/nightly_linux_release/lastBuild/testReport/rcl/copyright/). -## Testing +## Testing [4] -### Feature Testing +### Feature Testing [4.i] -Each feature in `rcl` has corresponding tests which simulate typical usage, and they are located in the `test` directory. +Most features in `rcl` has corresponding tests which simulate typical usage, and they are located in the [`test`](./test) directory. New features are required to have tests before being added. +Currently nightly test results can be seen here: +* [linux-aarch64_release](https://ci.ros2.org/view/nightly/job/nightly_linux-aarch64_release/lastBuild/testReport/rcl/) +* [linux-arm64_release](https://ci.ros2.org/view/nightly/job/nightly_linux_release/lastBuild/testReport/rcl/) +* [mac_osx_release](https://ci.ros2.org/view/nightly/job/nightly_osx_release/lastBuild/testReport/rcl/) +* [windows_release](https://ci.ros2.org/view/nightly/job/nightly_win_rel/lastBuild/testReport/rcl/) -### Public API Testing +### Public API Testing [4.ii] -Each part of the public API have 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, but are quantified by contributing to code coverage. +Most of the functionality of the declared API in this package is covered in its unit tests. Currently it has a line coverage of [77%](https://ci.ros2.org/job/ci_linux_coverage/85/cobertura/src_ros2_rcl_rcl_src_rcl/). -### Coverage -TODO fix link +### Coverage [4.iii] -`rcl` follows the recommendations for ROS Core packages in the [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#coverage), and opts to use branch coverage instead of line coverage. +`rcl` follows the recommendations for ROS Core packages in the [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#code-coverage), and opts to use line coverage instead of branch coverage. This includes: -- tracking and reporting branch coverage statistics -- achieving and maintaining branch coverage at or above 95% +- tracking and reporting line coverage statistics - no lines are manually skipped in coverage calculations Changes are required to make a best effort to keep or increase coverage before being accepted, but decreases are allowed if properly justified and accepted by reviewers. -Current coverage statistics can be viewed here: - -TODO FIXME - -### Performance +Current coverage statistics can be viewed (77%) [here](https://ci.ros2.org/job/ci_linux_coverage/85/cobertura/src_ros2_rcl_rcl_src_rcl/). Current coverage statistics need to be improved to reach a higher quality level. -TODO fix link -`rcl` follows the recommendations for performance testing of C code in the [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#performance-c), and opts to do performance analysis on each release rather than each change. +### Performance [4.iv] -TODO how to run perf tests, where do they live, etc. +`rcl` does not conduct performance tests. It is not yet defined if this package requires performance testing and how addresses this topic. -TODO exclusions of parts of the code from perf testing listed here? or linked to? +### Linters and Static Analysis [4.v] -### Linters and Static Analysis +`rcl` uses and passes all the ROS2 standard linters and static analysis tools for a C++ package as described in the [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#linters-and-static-analysis). Passing implies there are no linter/static errors when testing against CI of supported platforms. -TODO fix link +Currently nightly test results can be seen here: +* [linux-aarch64_release](https://ci.ros2.org/view/nightly/job/nightly_linux-aarch64_release/lastBuild/testReport/rcl/) +* [linux-arm64_release](https://ci.ros2.org/view/nightly/job/nightly_linux_release/lastBuild/testReport/rcl/) +* [mac_osx_release](https://ci.ros2.org/view/nightly/job/nightly_osx_release/lastBuild/testReport/rcl/) +* [windows_release](https://ci.ros2.org/view/nightly/job/nightly_win_rel/lastBuild/testReport/rcl/) -`rcl` uses and passes all the standard linters and static analysis tools for a C package as described in the [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#linters-and-static-analysis). - -TODO any qualifications on what "passing" means for certain linters - -## Dependencies +## Dependencies [5] Below are evaluations of each of `rcl`'s run-time and build-time dependencies that have been determined to influence the quality. It has several "buildtool" dependencies, which do not affect the resulting quality of the package, because they do not contribute to the public library API. It also has several test dependencies, which do not affect the resulting quality of the package, because they are only used to build and run the test code. -### `rmw` +### Direct Runtime ROS Dependencies [5.i] -TODO fix link +### `rmw` The `rmw` package provides the API used by `rcl` to interact with the underlying middleware in an abstract way. -It is **Quality Level 1**, see its [Quality Declaration document](FIX). +It is **Quality Level 4**, see its [Quality Declaration document](https://github.com/ros2/rmw/rmw/QUALITY_DECLARATION.md). ### `rcl_interfaces` -TODO fix link - The `rcl_interfaces` package provides some common ROS Message and ROS Service types which are used to implement certain client library features. -It is **Quality Level 1**, see its [Quality Declaration document](FIX). +It is **Quality Level 4**, see its [Quality Declaration document](https://github.com/ros2/rcl_interfaces/blob/master/rcl_interfaces/QUALITY_DECLARATION.md). ### `rcl_logging_spdlog` -TODO fix link -TODO should this direct dependency be here? - The `rcl_logging_spdlog` package provides the default logging implementation by wrapping the `spdlog` library. -It is **Quality Level 1**, see its [Quality Declaration document](FIX). +It is **Quality Level 4**, see its [Quality Declaration document](https://github.com/ros2/rcl_logging/rcl_logging_spdlog/Quality_Declaration.md). ### `rcl_yaml_param_parser` -TODO fix link - The `rcl_yaml_param_parser` package provides an API that is used to parse YAML configuration files which may be used to configure ROS and specific nodes. -It is **Quality Level 1**, see its [Quality Declaration document](FIX). +It is **Quality Level 4**, see its [Quality Declaration document](https://github.com/ros2/rcl/tree/master/rcl_yaml_param_parser/Quality_Declaration.md). ### `rcutils` -TODO fix link - The `rcutils` package provides an API which contains common utilities and data structures needed when programming in C. -It is **Quality Level 1**, see its [Quality Declaration document](FIX). +It is **Quality Level 4**, see its [Quality Declaration document](https://github.com/ros2/rcutils/blob/master/QUALITY_DECLARATION.md). ### `rmw_implementation` -TODO fix link - The `rmw_implementation` package provides access to the default rmw implementation, and provides the ability to dynamically switch rmw implementations if more than one is available. -It is **Quality Level 1**, see its [Quality Declaration document](FIX). - -### `rosidl_generator_c` +It is **Quality Level 4**, see its [Quality Declaration document](https://github.com/ros2/rmw_implementation/blob/master/QUALITY_DECLARATION.md). -TODO fix link +### `rosidl_runtime_c` -The `rosidl_generator_c` package provides templates for generating data structures in C based on user defined ROS Messages and ROS Services, as well as associated support functions for those types. -`rcl` uses this pacakge because it uses the C instances of these user defined types in some cases, in combination with the types defined in the `rcl_interfaces` package. +The `rosidl_runtime_c` package provides runtime interfaces in C based on user defined ROS Messages and ROS Services, as well as associated support functions for those types. -It is **Quality Level 1**, see its [Quality Declaration document](FIX). +It is **Quality Level 4**, see its [Quality Declaration document](https://github.com/ros2/rosidl/tree/master/rosidl_runtime_c/Quality_Declaration.md). -### `tinydir_vendor` - -TODO fix link +### `tracetools` -The `tinydir_vendor` package wraps the third-party library called `tinydir`, which itself provides some basic filesystem operations. +The `tracetools` package provides utilities for instrumenting the code in `rcl` so that it may be traced for debugging and performance analysis. -It is **Quality Level 1**, see its [Quality Declaration document](FIX). +It is **Quality Level 4**, see its [Quality Declaration document](https://gitlab.com/micro-ROS/ros_tracing/ros2_tracing/-/blob/master/tracetools/QUALITY_DECLARATION.md). -### `tracetools` +### Optional Direct Runtime ROS Dependencies [5.ii] -TODO fix link +`rcl` has no optional Direct Runtime ROS dependencies that need to be considered for this declaration. -The `tracetools` package provides utilities for instrumenting the code in `rcl` so that it may be traced for debugging and performance analysis. +### Direct Runtime non-ROS Dependency [5.iii] -It is **Quality Level 1**, see its [Quality Declaration document](FIX). +`rcl` has no Direct Runtime non-ROS dependencies that need to be considered for this declaration. -## Platform Support +## Platform Support [6] `rcl` supports all of the tier 1 platforms as described in [REP-2000](https://www.ros.org/reps/rep-2000.html#support-tiers), and tests each change against all of them. -TODO make additional statements about non-tier 1 platforms? +## Vulnerability Disclosure Policy [7.i] + +`rcl` does not have a Vulnerability Disclosure Policy. + +# Current status Summary + +The chart below compares the requirements in the REP-2004 with the current state of the `rcl` package. + +|Number| Requirement| Current state | +|--|--|--| +|1| **Version policy** |---| +|1.i|Version Policy available | ✓ | +|1.ii|Stable version |☓| +|1.iii|Declared public API|✓| +|1.iv|API stability policy|✓| +|1.v|ABI stability policy|✓| +|1.vi_|API/ABI stable within ros distribution|✓| +|2| **Change control process** |---| +|2.i| All changes occur on change request | ✓| +|2.ii| Contributor origin (DCO, CLA, etc) | ✓| +|2.iii| Peer review policy | ✓ | +|2.iv| CI policy for change requests | ✓ | +|2.v| Documentation policy for change requests | ✓ | +|3| **Documentation** | --- | +|3.i| Per feature documentation | ☓ | +|3.ii| Per public API item documentation | * | +|3.iii| Declared License(s) | ✓ | +|3.iv| Copyright in source files| ✓ | +|3.v.a| Quality declaration linked to README | ✓ | +|3.v.b| Centralized declaration available for peer review |✓| +|4| Testing | --- | +|4.i| Feature items tests | ✓ | +|4.ii| Public API tests | ✓ | +|4.iii.a| Using coverage | * | +|4.iii.a| Coverage policy | ✓ | +|4.iv.a| Performance tests (if applicable) | ☓ | +|4.iv.b| Performance tests policy| ✓ | +|4.v.a| Code style enforcement (linters)| ✓ | +|4.v.b| Use of static analysis tools | ✓ | +|5| Dependencies | --- | +|5.i| Must not have ROS lower level dependencies | ✓ | +|5.ii| Optional ROS lower level dependencies| ✓ | +|5.iii| Justifies quality use of non-ROS dependencies |✓| +|6| Platform support | --- | +|6.i| Support targets Tier1 ROS platforms| ✓ | +|7| Security | --- | +|7.i| Vulnerability Disclosure Policy | ☓ | From 169614fb79f13e104f0cc1123b1557e7538388f7 Mon Sep 17 00:00:00 2001 From: Jorge Perez Date: Fri, 1 May 2020 17:14:04 -0300 Subject: [PATCH 3/7] Fix README.md files accordingly for the rcl package Signed-off-by: Jorge Perez --- README.md | 23 +++++------------------ rcl/README.md | 6 ++++++ 2 files changed, 11 insertions(+), 18 deletions(-) create mode 100644 rcl/README.md diff --git a/README.md b/README.md index aad6f95b1..26eb44cea 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,8 @@ This repository contains several packages which are all related to the `rcl` package. -### Packages +## Packages -#### rcl - -Library to support implementation of language specific ROS Client Libraries. - -This package claims to be in the **Quality Level 1** category, see the [Quality Declaration](./rcl/QUALITY_DECLARATION.md) for more details. - -#### rcl_action - -Package containing a C-based ROS action implementation. - -#### rcl_lifecycle - -Package containing a C-based lifecycle implementation. - -#### rcl_yaml_parm_parser - -Package containing various utility types and functions for C. + - rcl + - rcl_action + - rcl_lifecycle + - rcl_yaml_parm_parser diff --git a/rcl/README.md b/rcl/README.md new file mode 100644 index 000000000..f472a6585 --- /dev/null +++ b/rcl/README.md @@ -0,0 +1,6 @@ +## rcl + +Library to support implementation of language specific ROS Client Libraries. + +This package claims to be in the **Quality Level 4** category, see the [Quality Declaration](./QUALITY_DECLARATION.md) for more details. + From 09560f8816c20afeeadbc0744bd6b26155c35e0d Mon Sep 17 00:00:00 2001 From: Jorge Perez Date: Fri, 1 May 2020 17:39:39 -0300 Subject: [PATCH 4/7] Fix minor typos Signed-off-by: Jorge Perez --- rcl/QUALITY_DECLARATION.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/rcl/QUALITY_DECLARATION.md b/rcl/QUALITY_DECLARATION.md index 5cab08a84..ec4b43cc9 100644 --- a/rcl/QUALITY_DECLARATION.md +++ b/rcl/QUALITY_DECLARATION.md @@ -46,11 +46,11 @@ This package uses DCO as its confirmation of contributor origin policy. More inf ### Peer Review Policy [2.iii] -All pull request will be peer-reviewed, check [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#change-control-process) for additional information. +All pull requests will be peer-reviewed, check [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#change-control-process) for additional information. ### Continuous Integration [2.iv] -All pull request must pass CI on all [tier 1 platforms](https://www.ros.org/reps/rep-2000.html#support-tiers). +All pull requests must pass CI on all [tier 1 platforms](https://www.ros.org/reps/rep-2000.html#support-tiers). Currently nightly results can be seen here: * [linux-aarch64_release](https://ci.ros2.org/view/nightly/job/nightly_linux-aarch64_release/lastBuild/testReport/rcl/) @@ -94,7 +94,7 @@ Most features in `rcl` has corresponding tests which simulate typical usage, and New features are required to have tests before being added. Currently nightly test results can be seen here: * [linux-aarch64_release](https://ci.ros2.org/view/nightly/job/nightly_linux-aarch64_release/lastBuild/testReport/rcl/) -* [linux-arm64_release](https://ci.ros2.org/view/nightly/job/nightly_linux_release/lastBuild/testReport/rcl/) +* [linux_release](https://ci.ros2.org/view/nightly/job/nightly_linux_release/lastBuild/testReport/rcl/) * [mac_osx_release](https://ci.ros2.org/view/nightly/job/nightly_osx_release/lastBuild/testReport/rcl/) * [windows_release](https://ci.ros2.org/view/nightly/job/nightly_win_rel/lastBuild/testReport/rcl/) @@ -127,7 +127,7 @@ Current coverage statistics can be viewed (77%) [here](https://ci.ros2.org/job/c Currently nightly test results can be seen here: * [linux-aarch64_release](https://ci.ros2.org/view/nightly/job/nightly_linux-aarch64_release/lastBuild/testReport/rcl/) -* [linux-arm64_release](https://ci.ros2.org/view/nightly/job/nightly_linux_release/lastBuild/testReport/rcl/) +* [linux_release](https://ci.ros2.org/view/nightly/job/nightly_linux_release/lastBuild/testReport/rcl/) * [mac_osx_release](https://ci.ros2.org/view/nightly/job/nightly_osx_release/lastBuild/testReport/rcl/) * [windows_release](https://ci.ros2.org/view/nightly/job/nightly_win_rel/lastBuild/testReport/rcl/) From 3589922684681990f600d7f9169a415598729418 Mon Sep 17 00:00:00 2001 From: Jorge Perez Date: Mon, 4 May 2020 19:19:52 -0300 Subject: [PATCH 5/7] Fix minor issues according to peer review Signed-off-by: Jorge Perez --- rcl/QUALITY_DECLARATION.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/rcl/QUALITY_DECLARATION.md b/rcl/QUALITY_DECLARATION.md index ec4b43cc9..b52ff88cc 100644 --- a/rcl/QUALITY_DECLARATION.md +++ b/rcl/QUALITY_DECLARATION.md @@ -28,7 +28,7 @@ All installed headers are in the [`include`](./include/rcl) directory of the pac ### ABI Stability Policy [1.v] -`rcl` contains C++ code and therefore must be concerned with ABI stability, and will maintain ABI stability within a ROS distribution. +`rcl` contains C code and therefore must be concerned with ABI stability, and will maintain ABI stability within a ROS distribution. ### ABI and ABI Stability Within a Released ROS Distribution [1.vi] @@ -90,7 +90,7 @@ There is an automated test which runs a linter that ensures each file has at lea ### Feature Testing [4.i] -Most features in `rcl` has corresponding tests which simulate typical usage, and they are located in the [`test`](./test) directory. +Most features in `rcl` have corresponding tests which simulate typical usage, and they are located in the [`test`](./test) directory. New features are required to have tests before being added. Currently nightly test results can be seen here: * [linux-aarch64_release](https://ci.ros2.org/view/nightly/job/nightly_linux-aarch64_release/lastBuild/testReport/rcl/) @@ -119,7 +119,7 @@ Current coverage statistics can be viewed (77%) [here](https://ci.ros2.org/job/c ### Performance [4.iv] -`rcl` does not conduct performance tests. It is not yet defined if this package requires performance testing and how addresses this topic. +`rcl` does not conduct performance tests. ### Linters and Static Analysis [4.v] From b1d4b4272c147ff7bc55445682d4ce3ccb4e4a0f Mon Sep 17 00:00:00 2001 From: Jorge Perez Date: Tue, 5 May 2020 11:14:46 -0300 Subject: [PATCH 6/7] Address peer review comments Signed-off-by: Jorge Perez --- rcl/QUALITY_DECLARATION.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/rcl/QUALITY_DECLARATION.md b/rcl/QUALITY_DECLARATION.md index b52ff88cc..fb5881401 100644 --- a/rcl/QUALITY_DECLARATION.md +++ b/rcl/QUALITY_DECLARATION.md @@ -102,7 +102,6 @@ Currently nightly test results can be seen here: Most of the functionality of the declared API in this package is covered in its unit tests. Currently it has a line coverage of [77%](https://ci.ros2.org/job/ci_linux_coverage/85/cobertura/src_ros2_rcl_rcl_src_rcl/). - ### Coverage [4.iii] `rcl` follows the recommendations for ROS Core packages in the [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#code-coverage), and opts to use line coverage instead of branch coverage. @@ -116,7 +115,6 @@ Changes are required to make a best effort to keep or increase coverage before b Current coverage statistics can be viewed (77%) [here](https://ci.ros2.org/job/ci_linux_coverage/85/cobertura/src_ros2_rcl_rcl_src_rcl/). Current coverage statistics need to be improved to reach a higher quality level. - ### Performance [4.iv] `rcl` does not conduct performance tests. @@ -140,49 +138,49 @@ It also has several test dependencies, which do not affect the resulting quality ### Direct Runtime ROS Dependencies [5.i] -### `rmw` +#### `rmw` The `rmw` package provides the API used by `rcl` to interact with the underlying middleware in an abstract way. It is **Quality Level 4**, see its [Quality Declaration document](https://github.com/ros2/rmw/rmw/QUALITY_DECLARATION.md). -### `rcl_interfaces` +#### `rcl_interfaces` The `rcl_interfaces` package provides some common ROS Message and ROS Service types which are used to implement certain client library features. It is **Quality Level 4**, see its [Quality Declaration document](https://github.com/ros2/rcl_interfaces/blob/master/rcl_interfaces/QUALITY_DECLARATION.md). -### `rcl_logging_spdlog` +#### `rcl_logging_spdlog` The `rcl_logging_spdlog` package provides the default logging implementation by wrapping the `spdlog` library. It is **Quality Level 4**, see its [Quality Declaration document](https://github.com/ros2/rcl_logging/rcl_logging_spdlog/Quality_Declaration.md). -### `rcl_yaml_param_parser` +#### `rcl_yaml_param_parser` The `rcl_yaml_param_parser` package provides an API that is used to parse YAML configuration files which may be used to configure ROS and specific nodes. It is **Quality Level 4**, see its [Quality Declaration document](https://github.com/ros2/rcl/tree/master/rcl_yaml_param_parser/Quality_Declaration.md). -### `rcutils` +#### `rcutils` The `rcutils` package provides an API which contains common utilities and data structures needed when programming in C. It is **Quality Level 4**, see its [Quality Declaration document](https://github.com/ros2/rcutils/blob/master/QUALITY_DECLARATION.md). -### `rmw_implementation` +#### `rmw_implementation` The `rmw_implementation` package provides access to the default rmw implementation, and provides the ability to dynamically switch rmw implementations if more than one is available. It is **Quality Level 4**, see its [Quality Declaration document](https://github.com/ros2/rmw_implementation/blob/master/QUALITY_DECLARATION.md). -### `rosidl_runtime_c` +#### `rosidl_runtime_c` The `rosidl_runtime_c` package provides runtime interfaces in C based on user defined ROS Messages and ROS Services, as well as associated support functions for those types. It is **Quality Level 4**, see its [Quality Declaration document](https://github.com/ros2/rosidl/tree/master/rosidl_runtime_c/Quality_Declaration.md). -### `tracetools` +#### `tracetools` The `tracetools` package provides utilities for instrumenting the code in `rcl` so that it may be traced for debugging and performance analysis. @@ -200,7 +198,9 @@ It is **Quality Level 4**, see its [Quality Declaration document](https://gitlab `rcl` supports all of the tier 1 platforms as described in [REP-2000](https://www.ros.org/reps/rep-2000.html#support-tiers), and tests each change against all of them. -## Vulnerability Disclosure Policy [7.i] +## Security [7] + +### Vulnerability Disclosure Policy [7.i] `rcl` does not have a Vulnerability Disclosure Policy. @@ -208,7 +208,7 @@ It is **Quality Level 4**, see its [Quality Declaration document](https://gitlab The chart below compares the requirements in the REP-2004 with the current state of the `rcl` package. -|Number| Requirement| Current state | +|Number| Requirement| Current state | |--|--|--| |1| **Version policy** |---| |1.i|Version Policy available | ✓ | From 24ae51ed61f515f7d48abd91a5833e19fd57f8d7 Mon Sep 17 00:00:00 2001 From: Jorge Perez Date: Tue, 5 May 2020 11:19:57 -0300 Subject: [PATCH 7/7] Improve current state Feature documentation Signed-off-by: Jorge Perez --- rcl/QUALITY_DECLARATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rcl/QUALITY_DECLARATION.md b/rcl/QUALITY_DECLARATION.md index fb5881401..c2727609f 100644 --- a/rcl/QUALITY_DECLARATION.md +++ b/rcl/QUALITY_DECLARATION.md @@ -66,7 +66,7 @@ All pull requests must resolve related documentation changes before merging. ### Feature Documentation [3.i] -`rcl` does not have a documented feature list. +`rcl` provides the main elements of its API listed using doxygen. Refer to the [ROS2 concepts](https://index.ros.org/doc/ros2/Concepts/) and [ROS2 Client Libraries](https://index.ros.org/doc/ros2/Concepts/ROS-2-Client-Libraries/) pages for reference of elements covered by this package. ### Public API Documentation [3.ii]