Skip to content

Commit ff58b60

Browse files
snapesnape
committed
docs: add ROS package manifest and quality declaration
1 parent 445dcdc commit ff58b60

File tree

3 files changed

+340
-0
lines changed

3 files changed

+340
-0
lines changed

‎.gitattributes‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,7 @@
5555
*.md text diff=markdown whitespace-md
5656
*.properties text whitespace-4
5757
*.txt text
58+
*.xml text
5859
*.yaml text whitespace-2
5960
*.yml text whitespace-2
6061

‎QUALITY_DECLARATION.md‎

Lines changed: 280 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,280 @@
1+
<!--
2+
QUALITY_DECLARATION.md
3+
RVO2 Library Java
4+
5+
SPDX-FileCopyrightText: 2008 University of North Carolina at Chapel Hill
6+
SPDX-License-Identifier: CC-BY-SA-4.0
7+
8+
Creative Commons Attribution-ShareAlike 4.0 International Public License
9+
10+
You are free to:
11+
12+
* Share -- copy and redistribute the material in any medium or format
13+
14+
* ShareAlike -- If you remix, transform, or build upon the material, you must
15+
distribute your contributions under the same license as the original
16+
17+
* Adapt -- remix, transform, and build upon the material for any purpose, even
18+
commercially.
19+
20+
The licensor cannot revoke these freedoms as long as you follow the license
21+
terms.
22+
23+
Under the following terms:
24+
25+
* Attribution -- You must give appropriate credit, provide a link to the
26+
license, and indicate if changes were made. You may do so in any reasonable
27+
manner, but not in any way that suggests the licensor endorses you or your
28+
use.
29+
30+
* No additional restrictions -- You may not apply legal terms or technological
31+
measures that legally restrict others from doing anything the license
32+
permits.
33+
34+
Notices:
35+
36+
* You do not have to comply with the license for elements of the material in
37+
the public domain or where your use is permitted by an applicable exception
38+
or limitation.
39+
40+
* No warranties are given. The license may not give you all of the permissions
41+
necessary for your intended use. For example, other rights such as publicity,
42+
privacy, or moral rights may limit how you use the material.
43+
44+
Please send all bug reports to <geom@cs.unc.edu>.
45+
46+
The authors may be contacted via:
47+
48+
Jur van den Berg, Stephen J. Guy, Jamie Snape, Ming C. Lin, Dinesh Manocha
49+
Dept. of Computer Science
50+
201 S. Columbia St.
51+
Frederick P. Brooks, Jr. Computer Science Bldg.
52+
Chapel Hill, N.C. 27599-3175
53+
United States of America
54+
55+
<https://gamma.cs.unc.edu/RVO2/>
56+
-->
57+
58+
# `RVO2 Library Java` Quality Declaration
59+
60+
The package `RVO2 Library Java` claims to be in the **Quality Level 2** category.
61+
62+
Below are the rationales, notes, and caveats for this claim, organized by each
63+
requirement listed in the Package Requirements for Quality Level 2 in
64+
[REP-2004](https://www.ros.org/reps/rep-2004.html).
65+
66+
## Version Policy [1]
67+
68+
### Version Scheme [1.i]
69+
70+
`RVO2 Library Java` uses [Semantic Versioning 2.0.0](https://semver.org/), and
71+
is at version `2.1.0`. The version is declared in `CMakeLists.txt` and
72+
`MODULE.bazel`.
73+
74+
### Version Stability [1.ii]
75+
76+
`RVO2 Library Java` is at a stable version (`2.1.0`), which is greater than
77+
`1.0.0`.
78+
79+
### Public API Declaration [1.iii]
80+
81+
The public API of `RVO2 Library Java` is the set of types declared in the
82+
[`edu.unc.cs.gamma.rvo`](rvo/src/main/java/edu/unc/cs/gamma/rvo/) package:
83+
`Simulator`, `AgentParameters`, and `Line`. Internal implementation details in
84+
`Agent`, `KdTree`, `Obstacle`, and `RVOMath` are not part of the public API.
85+
86+
### API Stability Within a Released Version [1.iv]
87+
88+
The public API is stable across patch and minor versions. Breaking API changes
89+
are only introduced in new major versions.
90+
91+
### Binary Compatibility Within a Released Version [1.v]
92+
93+
Binary compatibility is maintained across patch versions within the same
94+
`major.minor` release series. New major or minor versions may introduce
95+
binary-incompatible changes.
96+
97+
## Change Control Process [2]
98+
99+
### Change Requests [2.i]
100+
101+
All changes to `RVO2 Library Java` are submitted through pull requests on
102+
[GitHub](https://github.com/snape/RVO2-Java). Direct commits to the `main`
103+
branch are not permitted outside of automated tooling.
104+
105+
### Contributor Origin [2.ii]
106+
107+
All contributors must sign off on their commits using the
108+
[Developer Certificate of Origin (DCO)](https://developercertificate.org/),
109+
enforced via the DCO GitHub App on every pull request.
110+
111+
### Peer Review Policy [2.iii]
112+
113+
As a single-maintainer project, all changes are reviewed by the primary
114+
maintainer [@snape](https://github.com/snape) before merging.
115+
116+
### Continuous Integration [2.iv]
117+
118+
CI is performed via GitHub Actions on every push and pull request to `main`,
119+
and on a daily schedule:
120+
121+
- [`.github/workflows/ci.yml`](.github/workflows/ci.yml): builds and tests
122+
with Bazel, CMake, and Gradle on AlmaLinux, Arch Linux, Fedora, openSUSE,
123+
and Ubuntu (amd64 and arm64), and macOS (arm64); CMake and Gradle
124+
additionally on Alpine Linux (amd64) and Windows (amd64). CMake builds
125+
enable `BUILD_DOCUMENTATION`, `BUILD_TESTING`, and `WARNINGS_AS_ERRORS`.
126+
- [`.github/workflows/codeql.yml`](.github/workflows/codeql.yml): runs GitHub
127+
CodeQL semantic code analysis for Java on a weekly schedule.
128+
129+
### Documentation Policy [2.v]
130+
131+
Changes are documented through commit messages and pull request descriptions
132+
on GitHub.
133+
134+
## Documentation [3]
135+
136+
### Feature Documentation [3.i]
137+
138+
All features of `RVO2 Library Java` are documented in the Javadoc markup
139+
within the [`edu.unc.cs.gamma.rvo`](rvo/src/main/java/edu/unc/cs/gamma/rvo/)
140+
package, including a usage guide, parameter overview, and example code. Three
141+
annotated example programs
142+
([`blocks/src/main/java/edu/unc/cs/gamma/rvo/examples/Blocks.java`](blocks/src/main/java/edu/unc/cs/gamma/rvo/examples/Blocks.java),
143+
[`circle/src/main/java/edu/unc/cs/gamma/rvo/examples/Circle.java`](circle/src/main/java/edu/unc/cs/gamma/rvo/examples/Circle.java),
144+
[`roadmap/src/main/java/edu/unc/cs/gamma/rvo/examples/Roadmap.java`](roadmap/src/main/java/edu/unc/cs/gamma/rvo/examples/Roadmap.java))
145+
demonstrate typical usage patterns covering agents, obstacles, and step-wise
146+
simulation.
147+
148+
### Public API Documentation [3.ii]
149+
150+
All public API elements are documented with Javadoc markup. HTML documentation
151+
is generated from the source using `cmake -DBUILD_DOCUMENTATION=ON`,
152+
`bazel build`, or `./gradlew javadoc`, and installed with the library.
153+
154+
### License [3.iii]
155+
156+
Source code is licensed under the
157+
[Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0).
158+
Documentation is licensed under the
159+
[Creative Commons Attribution-ShareAlike 4.0 International (CC-BY-SA-4.0)](https://creativecommons.org/licenses/by-sa/4.0/)
160+
Public License.
161+
162+
The project uses the [REUSE Specification](https://reuse.software/) for license
163+
compliance. Every source file contains machine-readable SPDX license and
164+
copyright headers, and license texts are provided in the [`LICENSES/`](LICENSES/)
165+
directory. License compliance is verified by the `reuse` pre-commit hook.
166+
167+
### Copyright Statement [3.iv]
168+
169+
Copyright is held by the University of North Carolina at Chapel Hill. All
170+
source files include the SPDX copyright notice:
171+
172+
```
173+
SPDX-FileCopyrightText: 2008 University of North Carolina at Chapel Hill
174+
```
175+
176+
### Quality Declaration [3.v]
177+
178+
This document is the quality declaration for `RVO2 Library Java` and is linked
179+
from the project README.
180+
181+
## Testing [4]
182+
183+
### Feature Testing [4.i]
184+
185+
Three system-level simulation scenarios form the test suite, run via `ctest`
186+
(CMake), `bazel test` (Bazel), and `./gradlew test` (Gradle):
187+
188+
- **Blocks**: 100 agents split into four groups navigating through a narrow
189+
passage formed by four obstacles.
190+
- **Circle**: 250 agents initially distributed on a circle moving to their
191+
antipodal positions.
192+
- **Roadmap**: The Blocks scenario augmented with roadmap-based global path
193+
planning.
194+
195+
These scenarios exercise all documented features of the library, including
196+
agent management, obstacle processing, the k-D tree spatial index, and
197+
step-wise simulation.
198+
199+
### Public API Testing [4.ii]
200+
201+
The three simulation scenarios collectively exercise all major public API
202+
functions of `Simulator`, `AgentParameters`, and `Line`. Dedicated unit tests
203+
for individual API functions are not currently present.
204+
205+
### Coverage [4.iii]
206+
207+
Code coverage is not currently tracked. The three simulation scenarios provide
208+
broad functional coverage of the library, but no formal coverage measurement
209+
or policy is in place. This is a known gap relative to Quality Level 2
210+
requirements.
211+
212+
### Performance [4.iv]
213+
214+
No formal performance regression tests are in place. The simulation scenarios
215+
implicitly exercise performance characteristics of the library (e.g., the
216+
Circle scenario with 250 agents, and the Blocks scenario with obstacle
217+
processing), but no automated performance benchmarks are run in CI.
218+
219+
### Linters and Static Analysis [4.v]
220+
221+
The following linters and static analysis tools are enforced, with all warnings
222+
treated as errors in CI:
223+
224+
- **checkstyle**: code style enforcement via
225+
[`config/checkstyle/checkstyle.xml`](config/checkstyle/checkstyle.xml)
226+
- **ErrorProne**: static analysis via the `net.ltgt.errorprone` Gradle plugin
227+
- **NullAway**: null safety enforcement via ErrorProne with
228+
`NullAway:AnnotatedPackages = edu.unc.cs.gamma.rvo`
229+
- **buildifier**: Bazel file formatting via [`.buildifier.json`](.buildifier.json)
230+
- **CodeQL**: GitHub's semantic code analysis for Java via
231+
[`.github/workflows/codeql.yml`](.github/workflows/codeql.yml)
232+
- **pre-commit hooks**: `codespell` (spell checking), `yamllint`, `actionlint`
233+
(workflow validation), REUSE compliance, case-conflict detection, and
234+
trailing-whitespace removal via [`.pre-commit-config.yaml`](.pre-commit-config.yaml)
235+
236+
## Dependencies [5]
237+
238+
### Direct Runtime ROS Dependencies [5.i]
239+
240+
None.
241+
242+
### Optional Direct Runtime ROS Dependencies [5.ii]
243+
244+
None.
245+
246+
### Direct Runtime non-ROS Dependencies [5.iii]
247+
248+
- **Java Standard Library**: provided by the Java runtime (OpenJDK 21 or
249+
later). This is a de facto standard with no quality level concerns.
250+
- **Apache Commons Math** (`org.apache.commons:commons-math3:3.6.1`): provides
251+
the `Vector2D` type used throughout the public API. This is a widely-used,
252+
well-maintained Apache library.
253+
- **JSpecify** (`org.jspecify:jspecify:1.0.0`): provides standard null
254+
annotations used for static null safety analysis. This is a compile-time
255+
dependency only.
256+
257+
## Platform Support [6]
258+
259+
`RVO2 Library Java` is built and tested continuously via GitHub Actions on the
260+
following platforms:
261+
262+
| Platform | Architecture | Build System |
263+
|----------------|--------------|----------------------|
264+
| AlmaLinux 10 | amd64 | Bazel, CMake, Gradle |
265+
| Alpine Linux | amd64 | CMake, Gradle |
266+
| Arch Linux | amd64 | Bazel, CMake, Gradle |
267+
| Fedora | amd64 | Bazel, CMake, Gradle |
268+
| openSUSE Leap | amd64 | Bazel, CMake, Gradle |
269+
| Ubuntu | amd64, arm64 | Bazel, CMake, Gradle |
270+
| macOS | arm64 | Bazel, CMake, Gradle |
271+
| Windows | amd64 | CMake, Gradle |
272+
273+
## Security [7]
274+
275+
### Vulnerability Disclosure Policy [7.i]
276+
277+
The security policy is documented in
278+
[`.github/SECURITY.md`](.github/SECURITY.md). Vulnerability reports should be
279+
sent to [geom@cs.unc.edu](mailto:geom@cs.unc.edu). The current release is
280+
supported with security updates when practical.

‎package.xml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
<?xml version="1.0"?>
2+
<?xml-model href="http://download.ros.org/schema/package_format3.xsd"
3+
schematypens="http://www.w3.org/2001/XMLSchema"?>
4+
<!--
5+
package.xml
6+
RVO2 Library Java
7+
8+
SPDX-FileCopyrightText: 2008 University of North Carolina at Chapel Hill
9+
SPDX-License-Identifier: Apache-2.0
10+
11+
Licensed under the Apache License, Version 2.0 (the "License");
12+
you may not use this file except in compliance with the License.
13+
You may obtain a copy of the License at
14+
15+
https://www.apache.org/licenses/LICENSE-2.0
16+
17+
Unless required by applicable law or agreed to in writing, software
18+
distributed under the License is distributed on an "AS IS" BASIS,
19+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20+
See the License for the specific language governing permissions and
21+
limitations under the License.
22+
23+
Please send all bug reports to <geom@cs.unc.edu>.
24+
25+
The authors may be contacted via:
26+
27+
Jur van den Berg, Stephen J. Guy, Jamie Snape, Ming C. Lin, Dinesh Manocha
28+
Dept. of Computer Science
29+
201 S. Columbia St.
30+
Frederick P. Brooks, Jr. Computer Science Bldg.
31+
Chapel Hill, N.C. 27599-3175
32+
United States of America
33+
34+
<https://gamma.cs.unc.edu/RVO2/>
35+
-->
36+
<package format="3">
37+
<name>rvo2_java</name>
38+
<version>2.0.0</version>
39+
<description>Optimal Reciprocal Collision Avoidance for Java</description>
40+
41+
<maintainer email="geom@cs.unc.edu">Jamie Snape</maintainer>
42+
43+
<license>Apache-2.0</license>
44+
45+
<url type="website">https://gamma.cs.unc.edu/RVO2-Java/</url>
46+
<url type="repository">https://github.com/snape/RVO2</url>
47+
48+
<author>Jur van den Berg</author>
49+
<author>Stephen J. Guy</author>
50+
<author>Jamie Snape</author>
51+
<author>Ming C. Lin</author>
52+
<author>Dinesh Manocha</author>
53+
54+
<buildtool_depend>cmake</buildtool_depend>
55+
56+
<export>
57+
<build_type>cmake</build_type>
58+
</export>
59+
</package>

0 commit comments

Comments
 (0)