Skip to content

Commit f5b4ab3

Browse files
brawnerbrawner
authored
Add quality declarations for each package except test_msgs (#92)
* Create package-level READMEs and add some inline comments Signed-off-by: Stephen Brawner <[email protected]> * PR Fixup Signed-off-by: Stephen Brawner <[email protected]> * PR fixup Signed-off-by: Stephen Brawner <[email protected]> * Add QUALITY_DECLARATION for all but test_msgs Signed-off-by: Stephen Brawner <[email protected]> Switch QDs to their QL current-level (4) Signed-off-by: Stephen Brawner <[email protected]> * PR Fixup Signed-off-by: Stephen Brawner <[email protected]> * PR Fixup Signed-off-by: Stephen Brawner <[email protected]> * PR Fixup Signed-off-by: Stephen Brawner <[email protected]>
1 parent a3942b9 commit f5b4ab3

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

46 files changed

+1110
-118
lines changed

‎README.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,11 @@
11
# rcl_interfaces repository
22
This repository contains a set of packages that primarily contain interface files (.msg and .srv) which are used both to implement client library concepts and for testing.
3+
4+
# rcl_interface packages
5+
* [action_msgs](action_msgs/README.md): Messages and services for [ROS 2 actions](http://design.ros2.org/articles/actions.html)
6+
* [builtin_interfaces](builtin_interfaces/README.md): Message definitions for types in the OMG IDL Platform Specific Model
7+
* [composition_interfaces](composition_interfaces/README.md): Services for managing composeable nodes.
8+
* [lifecycle_msgs](lifecycle_msgs/README.md): Message and service definitions for managing lifecycle nodes.
9+
* [rcl_interfaces](rcl_interfaces/README.md): Message and service definitions for ROS client libraries
10+
* [rosgraph_msgs](rosgraph_msgs/README.md): Message definitions relating the ROS Computation Graph
11+
* test_msgs: Used exclusively for testing purposes

‎action_msgs/QUALITY_DECLARATION.md

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
This document is a declaration of software quality for the `action_msgs` package, based on the guidelines in [REP-2004](https://www.ros.org/reps/rep-2004.html).
2+
3+
# `action_msgs` Quality Declaration
4+
5+
The package `action_msgs` claims to be in the **Quality Level 4** category.
6+
7+
Below are the rationales, notes, and caveats for this claim, organized by each requirement listed in the [Package Requirements for Quality Level 4 in REP-2004](https://www.ros.org/reps/rep-2004.html).
8+
9+
## Version Policy [1]
10+
11+
### Version Scheme [1.i]
12+
13+
`action_msgs` 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).
14+
15+
### Version Stability [1.ii]
16+
17+
`action_msgs` is not yet at a stable version, i.e. `>= 1.0.0`.
18+
19+
### Public API Declaration [1.iii]
20+
21+
All message and service definition files located in `msg` and `srv` directories are considered part of the public API.
22+
23+
### API Stability Within a Released ROS Distribution [1.iv]/[1.vi]
24+
25+
`action_msgs` will not break public API within a released ROS distribution, i.e. no major releases once the ROS distribution is released.
26+
27+
### ABI Stability Within a Released ROS Distribution [1.v]/[1.vi]
28+
29+
`action_msgs` does not contain any C or C++ code and therefore will not affect ABI stability.
30+
31+
## Change Control Process [2]
32+
33+
`action_msgs` follows the recommended guidelines for ROS Core packages in the [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#package-requirements).
34+
35+
### Change Requests [2.i]
36+
37+
This package requires that all changes occur through a pull request.
38+
39+
### Contributor Origin [2.ii]
40+
41+
This package uses DCO as its confirmation of contributor origin policy. More information can be found in [CONTRIBUTING](../CONTRIBUTING.md).
42+
43+
### Peer Review Policy [2.iii]
44+
45+
Following the recommended guidelines for ROS Core packages, all pull requests must have at least 1 peer review.
46+
47+
### Continuous Integration [2.iv]
48+
49+
All pull request must pass CI on all [tier 1 platforms](https://www.ros.org/reps/rep-2000.html#support-tiers)
50+
51+
### Documentation Policy [2.v]
52+
53+
All pull requests must resolve related documentation changes before merging.
54+
55+
## Documentation
56+
57+
### Feature Documentation [3.i]
58+
59+
`action_msgs` has a list of provided [messages and services](README.md).
60+
New messages and services require their own documentation in order to be added.
61+
62+
### Public API Documentation [3.ii]
63+
64+
`action_msgs` has embedded API documentation, but it is not currently hosted.
65+
66+
### License [3.iii]
67+
68+
The license for `action_msgs` is Apache 2.0, the type is declared in the [package.xml](package.xml) manifest file, and a full copy of the license is in the repository level [LICENSE](../LICENSE) file.
69+
70+
There is an automated test which runs a linter that ensures each file has a license statement.
71+
72+
### Copyright Statements [3.iv]
73+
74+
The copyright holders each provide a statement of copyright in each source code file in `action_msgs`.
75+
76+
There is an automated test which runs a linter that ensures each file has at least one copyright statement.
77+
78+
The nightly test can be found at [here](http://build.ros2.org/view/Epr/job/Epr__rcl_interfaces__ubuntu_bionic_amd64/lastBuild/)
79+
80+
## Testing [4]
81+
82+
`action_msgs` is a package providing strictly message and service definitions and therefore does not require associated tests and has no coverage or performance requirements.
83+
84+
## Dependencies [5]
85+
86+
### Direct Runtime ROS Dependencies [5.i]/[5.ii]
87+
88+
`action_msgs` has the following runtime ROS dependencies:
89+
* `builtin_interfaces`
90+
* `rosidl_default_runtime`
91+
* `unique_identifier_msgs`
92+
93+
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.
94+
95+
### Direct Runtime Non-ROS Dependencies [5.iii]
96+
97+
`action_msgs` does not have any runtime non-ROS dependencies.
98+
99+
## Platform Support [6]
100+
101+
`action_msgs` 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.
102+
103+
Currently nightly results can be seen here:
104+
* [linux-aarch64_release](https://ci.ros2.org/view/nightly/job/nightly_linux-aarch64_release/lastBuild/testReport/action_msgs/)
105+
* [linux_release](https://ci.ros2.org/view/nightly/job/nightly_linux_release/lastBuild/testReport/action_msgs/)
106+
* [mac_osx_release](https://ci.ros2.org/view/nightly/job/nightly_osx_release/lastBuild/testReport/action_msgs/)
107+
* [windows_release](https://ci.ros2.org/view/nightly/job/nightly_win_rel/lastBuild/testReport/action_msgs/)
108+
109+
## Vulnerability Disclosure Policy [7.i]
110+
111+
This package does not yet have a Vulnerability Disclosure Policy

‎action_msgs/README.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# action_msgs
2+
This package contains several messages and services useful for ROS 2 actions.
3+
More information about actions can be found on its [design article](http://design.ros2.org/articles/actions.html).
4+
5+
For more information about ROS 2 interfaces, see [index.ros2.org](https://index.ros.org/doc/ros2/Concepts/About-ROS-Interfaces/).
6+
7+
## Messages (.msg)
8+
* [GoalInfo](msg/GoalInfo.msg): Goal identifier message, with a goal id and time stamp.
9+
* [GoalStatus](msg/GoalStatus.msg): Describes a goal's current state machine status.
10+
* [GoalStatusArray](msg/GoalStatusArray.msg): An array of [GoalStatus](msg/GoalStatus.msg) messages.
11+
12+
## Services (.srv)
13+
* [CancelGoal](srv/CancelGoal.srv): Cancel Goals either by id and/or timestamp.
14+
15+
## Quality Declaration
16+
This package claims to be in the **Quality Level 4** category, see the [Quality Declaration](QUALITY_DECLARATION.md) for more details.

‎action_msgs/msg/GoalStatus.msg

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,32 @@
1-
# An action goal can be in one of these states after it is accepted by an action server.
1+
# An action goal can be in one of these states after it is accepted by an action
2+
# server.
3+
#
24
# For more information, see http://design.ros2.org/articles/actions.html
5+
6+
# Indicates status has not been properly set.
37
int8 STATUS_UNKNOWN = 0
8+
9+
# The goal has been accepted and is awaiting execution.
410
int8 STATUS_ACCEPTED = 1
11+
12+
# The goal is currently being executed by the action server.
513
int8 STATUS_EXECUTING = 2
14+
15+
# The client has requested that the goal be canceled and the action server has
16+
# accepted the cancel request.
617
int8 STATUS_CANCELING = 3
18+
19+
# The goal was achieved successfully by the action server.
720
int8 STATUS_SUCCEEDED = 4
21+
22+
# The goal was canceled after an external request from an action client.
823
int8 STATUS_CANCELED = 5
24+
25+
# The goal was terminated by the action server without an external request.
926
int8 STATUS_ABORTED = 6
1027

11-
# Goal info (contains ID and timestamp)
28+
# Goal info (contains ID and timestamp).
1229
GoalInfo goal_info
1330

14-
# Goal status
31+
# Action goal state-machine status.
1532
int8 status

‎action_msgs/msg/GoalStatusArray.msg

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
1-
# An array of goal statuses
1+
# An array of goal statuses.
22
GoalStatus[] status_list

‎action_msgs/srv/CancelGoal.srv

Lines changed: 23 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -8,28 +8,39 @@
88
# - If the goal ID is not zero and timestamp is not zero, cancel the goal with
99
# the given ID and all goals accepted at or before the timestamp.
1010

11-
# Goal info containing an ID and timestamp
11+
# Goal info describing the goals to cancel, see above.
1212
GoalInfo goal_info
1313
---
14-
# Return codes
14+
##
15+
## Return codes.
16+
##
17+
1518
# Indicates the request was accepted without any errors.
16-
# One or more goals have transitioned to the CANCELING state.
17-
# The goals_canceling list is not empty.
19+
#
20+
# One or more goals have transitioned to the CANCELING state. The
21+
# goals_canceling list is not empty.
1822
int8 ERROR_NONE=0
23+
1924
# Indicates the request was rejected.
20-
# No goals have transitioned to the CANCELING state.
21-
# The goals_canceling list is empty.
25+
#
26+
# No goals have transitioned to the CANCELING state. The goals_canceling list is
27+
# empty.
2228
int8 ERROR_REJECTED=1
29+
2330
# Indicates the requested goal ID does not exist.
24-
# No goals have transitioned to the CANCELING state.
25-
# The goals_canceling list is empty.
31+
#
32+
# No goals have transitioned to the CANCELING state. The goals_canceling list is
33+
# empty.
2634
int8 ERROR_UNKNOWN_GOAL_ID=2
35+
2736
# Indicates the goal is not cancelable because it is already in a terminal state.
28-
# No goals have transitioned to the CANCELING state.
29-
# The goals_canceling list is empty.
37+
#
38+
# No goals have transitioned to the CANCELING state. The goals_canceling list is
39+
# empty.
3040
int8 ERROR_GOAL_TERMINATED=3
3141

32-
# Return code
42+
# Return code, see above definitions.
3343
int8 return_code
34-
# Goals that accepted the cancel request
44+
45+
# Goals that accepted the cancel request.
3546
GoalInfo[] goals_canceling

‎builtin_interfaces/QUALITY_DECLARATION.md

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
This document is a declaration of software quality for the `builtin_interfaces` package, based on the guidelines in [REP-2004](https://www.ros.org/reps/rep-2004.html).
2+
3+
# `builtin_interfaces` Quality Declaration
4+
5+
The package `builtin_interfaces` claims to be in the **Quality Level 4** category.
6+
7+
Below are the rationales, notes, and caveats for this claim, organized by each requirement listed in the [Package Requirements for Quality Level 4 in REP-2004](https://www.ros.org/reps/rep-2004.html).
8+
9+
## Version Policy [1]
10+
11+
### Version Scheme [1.i]
12+
13+
`builtin_interfaces` 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).
14+
15+
### Version Stability [1.ii]
16+
17+
`builtin_interfaces` is not yet at a stable version, i.e. `>= 1.0.0`.
18+
19+
### Public API Declaration [1.iii]
20+
21+
All message and service definition files located in `msg` and `srv` directories are considered part of the public API.
22+
23+
### API Stability Within a Released ROS Distribution [1.iv]/[1.vi]
24+
25+
`builtin_interfaces` will not break public API within a released ROS distribution, i.e. no major releases once the ROS distribution is released.
26+
27+
### ABI Stability Within a Released ROS Distribution [1.v]/[1.vi]
28+
29+
`builtin_interfaces` does not contain any C or C++ code and therefore will not affect ABI stability.
30+
31+
## Change Control Process [2]
32+
33+
`builtin_interfaces` follows the recommended guidelines for ROS Core packages in the [ROS 2 Developer Guide](https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#package-requirements).
34+
35+
### Change Requests [2.i]
36+
37+
This package requires that all changes occur through a pull request.
38+
39+
### Contributor Origin [2.ii]
40+
41+
This package uses DCO as its confirmation of contributor origin policy. More information can be found in [CONTRIBUTING](../CONTRIBUTING.md).
42+
43+
### Peer Review Policy [2.iii]
44+
45+
Following the recommended guidelines for ROS Core packages, all pull requests must have at least 1 peer review.
46+
47+
### Continuous Integration [2.iv]
48+
49+
All pull request must pass CI on all [tier 1 platforms](https://www.ros.org/reps/rep-2000.html#support-tiers)
50+
51+
### Documentation Policy [2.v]
52+
53+
All pull requests must resolve related documentation changes before merging.
54+
55+
## Documentation
56+
57+
### Feature Documentation [3.i]
58+
59+
`builtin_interfaces` has a list of provided [messages and services](README.md).
60+
New messages and services require their own documentation in order to be added.
61+
62+
### Public API Documentation [3.ii]
63+
64+
`builtin_interfaces` has embedded API documentation, but it is not currently hosted.
65+
66+
### License [3.iii]
67+
68+
The license for `builtin_interfaces` is Apache 2.0, the type is declared in the [package.xml](package.xml) manifest file, and a full copy of the license is in the repository level [LICENSE](../LICENSE) file.
69+
70+
There is an automated test which runs a linter that ensures each file has a license statement.
71+
72+
### Copyright Statements [3.iv]
73+
74+
The copyright holders each provide a statement of copyright in each source code file in `builtin_interfaces`.
75+
76+
There is an automated test which runs a linter that ensures each file has at least one copyright statement.
77+
78+
The nightly test can be found at [here](http://build.ros2.org/view/Epr/job/Epr__rcl_interfaces__ubuntu_bionic_amd64/lastBuild/)
79+
80+
## Testing [4]
81+
82+
`builtin_interfaces` is a package providing strictly message and service definitions and therefore does not require associated tests and has no coverage or performance requirements.
83+
84+
## Dependencies [5]
85+
86+
### Direct Runtime ROS Dependencies [5.i]/[5.ii]
87+
88+
`builtin_interfaces` has the following ROS dependencies:
89+
* `rosidl_default_runtime`
90+
91+
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.
92+
93+
### Direct Runtime Non-ROS Dependencies [5.iii]
94+
95+
`builtin_interfaces` does not have any runtime non-ROS dependencies.
96+
97+
## Platform Support [6]
98+
99+
`builtin_interfaces` 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.
100+
101+
Currently nightly results can be seen here:
102+
* [linux-aarch64_release](https://ci.ros2.org/view/nightly/job/nightly_linux-aarch64_release/lastBuild/testReport/builtin_interfaces/)
103+
* [linux_release](https://ci.ros2.org/view/nightly/job/nightly_linux_release/lastBuild/testReport/builtin_interfaces/)
104+
* [mac_osx_release](https://ci.ros2.org/view/nightly/job/nightly_osx_release/lastBuild/testReport/builtin_interfaces/)
105+
* [windows_release](https://ci.ros2.org/view/nightly/job/nightly_win_rel/lastBuild/testReport/builtin_interfaces/)
106+
107+
## Vulnerability Disclosure Policy [7.i]
108+
109+
This package does not yet have a Vulnerability Disclosure Policy

‎builtin_interfaces/README.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# builtin_interfaces
2+
A package containing message definitions for types defined in the OMG IDL Platform Specific Model.
3+
4+
For more information about ROS 2 time, see [design.ros2.org](https://design.ros2.org/articles/clock_and_time.html).
5+
6+
For more information about ROS 2 interfaces, see [index.ros2.org](https://index.ros.org/doc/ros2/Concepts/About-ROS-Interfaces/).
7+
8+
## Messages (.msg)
9+
* [Duration](msg/Duration.msg): Describes a time duration composed of seconds and nanoseconds components.
10+
* [Time](msg/Time.msg): Describes a point in time, composed of seconds and nanoseconds components.
11+
12+
## Quality Declaration
13+
This package claims to be in the **Quality Level 4** category, see the [Quality Declaration](QUALITY_DECLARATION.md) for more details.

‎builtin_interfaces/msg/Duration.msg

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,8 @@
1+
# Duration defines a period between two time points. It is comprised of a
2+
# seconds component and a nanoseconds component.
3+
4+
# Seconds component, range is valid over any possible int32 value.
15
int32 sec
6+
7+
# Nanoseconds component in the range of [0, 10e9).
28
uint32 nanosec

‎builtin_interfaces/msg/Time.msg

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,7 @@
1+
# Time indicates a specific point in time, relative to a clock's 0 point.
2+
3+
# The seconds component, valid over all int32 values.
14
int32 sec
5+
6+
# The nanoseconds component, valid in the range [0, 10e9).
27
uint32 nanosec

0 commit comments

Comments
 (0)