Add Quality Declaration level 4 ament_index_cpp

ament_index_cpp/Quality_Declaration.md

@@ -0,0 +1,190 @@
+This document is a declaration of software quality for the `ament_index_cpp` package, based on the guidelines in [REP-2004](https://github.com/ros-infrastructure/rep/blob/rep-2004/rep-2004.rst).
+
+# `ament_index_cpp` Quality Declaration
+
+The package `ament_index_cpp` 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 Quality Categories in REP-2004](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#package-quality-categories)
+
+## Version Policy [1]
+
+### Version Scheme [1.i]
+
+`ament_index_cpp` 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)
+
+### Version Stability [1.ii]
+
+`ament_index_cpp` is not yet at a stable version, i.e. >= 1.0.0"
+
+### Public API Declaration [1.iii]
+
+The public API of `ament_index_cpp` is composed of the functions available in the headers of the package, available in the [include/ament_index_cpp/](include/ament_index_cpp/) folder.
+
+### API Stability Policy [1.iv]
+
+`ament_index_cpp` will not break public API within a released ROS distribution, i.e. no major releases once the ROS distribution is released.
+
+### ABI Stability Policy [1.v]
+
+`ament_index_cpp` 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]
+
+`ament_index_cpp` 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]
+
+`ament_index_cpp` 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).
+
+### 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)
+
+### Peer Review Policy [2.iii]
+
+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 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/ament_index_cpp/)
+* [linux_release](https://ci.ros2.org/view/nightly/job/nightly_linux_release/lastBuild/testReport/ament_index_cpp/)
+* [mac_osx_release](https://ci.ros2.org/view/nightly/job/nightly_osx_release/lastBuild/testReport/ament_index_cpp/)
+* [windows_release](https://ci.ros2.org/view/nightly/job/nightly_win_rel/lastBuild/testReport/ament_index_cpp/)
+
+###  Documentation Policy [2.v]
+
+All pull requests must resolve related documentation changes before merging.
+
+## Documentation [3]
+
+### Feature Documentation [3.i]
+
+`ament_index_cpp` does not have a documented feature list. Although it currently states part of its conceptual overview [here](https://github.com/ament/ament_cmake/blob/master/ament_cmake_core/doc/resource_index.md).
+
+### Public API Documentation [3.ii]
+
+Some `ament_index_cpp` API functions are documented using docstrings. However, this is not hosted anywhere.
+
+### License [3.iii]
+
+The license for `ament_index_cpp` 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/ament_index_cpp/) 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 `ament_index_cpp`.
+
+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/ament_index_cpp/copyright/).
+
+## Testing [4]
+
+### Feature Testing [4.i]
+
+Each feature in `ament_index_cpp` 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 results can be seen here:
+* [linux-aarch64_release](https://ci.ros2.org/view/nightly/job/nightly_linux-aarch64_release/lastBuild/testReport/ament_index_cpp/)
+* [linux_release](https://ci.ros2.org/view/nightly/job/nightly_linux_release/lastBuild/testReport/ament_index_cpp/)
+* [mac_osx_release](https://ci.ros2.org/view/nightly/job/nightly_osx_release/lastBuild/testReport/ament_index_cpp/)
+* [windows_release](https://ci.ros2.org/view/nightly/job/nightly_win_rel/lastBuild/testReport/ament_index_cpp/)
+
+New features are required to have tests before being added.
+
+### Public API Testing [4.ii]
+
+All the functionality of the declared API in this package is covered in its unit tests. Currently it has a line coverage of [99%](https://ci.ros2.org/job/ci_linux_coverage/85/cobertura/src_ament_ament_index_ament_index_cpp_src/).
+
+### Coverage [4.iii]
+
+`ament_index_cpp` 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 line coverage statistics
+- achieving and maintaining a reasonable branch line coverage (90-100%)
+- 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](https://ci.ros2.org/job/ci_linux_coverage/85/cobertura/src_ament_ament_index_ament_index_cpp_src/).
+
+### Performance [4.iv]
+
+`ament_index_cpp` does not conduct performance tests.
+
+### Linters and Static Analysis [4.v]
+
+`ament_index_cpp` 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.
+
+Currently nightly results can be seen here:
+* [linux-aarch64_release](https://ci.ros2.org/view/nightly/job/nightly_linux-aarch64_release/lastBuild/testReport/ament_index_cpp/)
+* [linux_release](https://ci.ros2.org/view/nightly/job/nightly_linux_release/lastBuild/testReport/ament_index_cpp/)
+* [mac_osx_release](https://ci.ros2.org/view/nightly/job/nightly_osx_release/lastBuild/testReport/ament_index_cpp/)
+* [windows_release](https://ci.ros2.org/view/nightly/job/nightly_win_rel/lastBuild/testReport/ament_index_cpp/)
+
+## Dependencies [5]
+
+`ament_index_cpp` has no run-time or build-time dependencies that need to be considered for this declaration.
+
+## Platform Support [6]
+
+`ament_index_cpp` 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.
+
+## Security
+
+### Vulnerability Disclosure Policy [7.i]
+
+`ament_index_cpp` 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 `ament_index_cpp` 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 | ☓ |
+
+Comparing this table with the [Quality Level Comparison Chart of REP2004](https://github.com/ros-infrastructure/rep/blob/master/rep-2004.rst#quality-level-comparison-chart) lead us to decide that this package qualifies to Quality Level 4.

ament_index_cpp/README.md

@@ -0,0 +1,9 @@
+# ament_index_cpp
+
+`ament_index_cpp` is a C++ API to access the ament resource index.
+
+See [https://github.com/ament/ament_cmake/blob/master/ament_cmake_core/doc/resource_index.md](https://github.com/ament/ament_cmake/blob/master/ament_cmake_core/doc/resource_index.md)  for documentation on the ament resource index.
+
+## Quality Declaration
+
+This package claims to be in the **Quality Level 4** category, see the [Quality Declaration](./Quality_Declaration.md) for more details.