From 16655e393becc190de53385186e0532d274f2f79 Mon Sep 17 00:00:00 2001 From: Jamie Snape Date: Sat, 4 Apr 2026 19:01:15 -0400 Subject: [PATCH 1/2] Add pre-commit checks and align lint/style configuration Introduce a pre-commit setup to enforce repository quality checks and normalize related formatting/lint behavior across the project. - add pre-commit configuration with hooks for: - REUSE license linting - YAML linting - codespell - clang-format and cpplint - standard pre-commit hygiene checks - GitHub Actions workflow linting (actionlint) - update cpplint configuration to ignore include-what-you-use and namespace indentation warnings - align clang-format pointer alignment setting - apply small consistency cleanups: - remove trailing whitespace/newline-only diffs in metadata/workflow files - normalize JSON formatting in metadata --- .clang-format | 1 + .gitattributes | 1 - .github/workflows/ci.yml | 2 +- .pre-commit-config.yaml | 55 ++++++++++++++++++++++++++++++++++++++++ .zenodo.json | 4 +-- CPPLINT.cfg | 2 ++ 6 files changed, 61 insertions(+), 4 deletions(-) create mode 100644 .pre-commit-config.yaml diff --git a/.clang-format b/.clang-format index 5aa6fda..cb78ca7 100644 --- a/.clang-format +++ b/.clang-format @@ -36,3 +36,4 @@ --- BasedOnStyle: Google +PointerAlignment: Right diff --git a/.gitattributes b/.gitattributes index 4487412..e442f1e 100644 --- a/.gitattributes +++ b/.gitattributes @@ -83,4 +83,3 @@ triggers whitespace-0 .github/** export-ignore .github/**/*.md linguist-documentation LICENSES/**/*.txt linguist-documentation linguist-vendored whitespace-0 - diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 045259a..4092182 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -121,7 +121,7 @@ jobs: wget -qO /usr/local/bin/bazelisk \ https://github.com/bazelbuild/bazelisk/releases/latest/download/bazelisk-linux-amd64 chmod +x /usr/local/bin/bazelisk - ln -s /usr/local/bin/bazelisk /usr/local/bin/bazel + ln -s /usr/local/bin/bazelisk /usr/local/bin/bazel shell: bash - name: checkout uses: actions/checkout@v6 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..944a516 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,55 @@ +--- +repos: + - repo: https://codeberg.org/fsfe/reuse-tool + rev: v6.2.0 + hooks: + - id: reuse-lint-file + + - repo: https://github.com/adrienverge/yamllint + rev: v1.38.0 + hooks: + - id: yamllint + args: + - --format + - parsable + + - repo: https://github.com/codespell-project/codespell + rev: v2.4.2 + hooks: + - id: codespell + + - repo: https://github.com/pocc/pre-commit-hooks + rev: master + hooks: + - id: clang-format + entry: >- + sh -c 'set -eu; + if [ "$(uname -s)" = Darwin ]; then + PATH="/opt/homebrew/opt/llvm/bin:${PATH}"; + fi; + exec clang-format-hook "$@"' -- + - id: cpplint + + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v6.0.0 + hooks: + - id: check-case-conflict + - id: check-json + - id: check-merge-conflict + - id: check-yaml + - id: end-of-file-fixer + - id: trailing-whitespace + exclude: (?i)\.(markdown|md)$ + + - repo: https://github.com/rhysd/actionlint + rev: v1.7.12 + hooks: + - id: actionlint + args: + - -oneline + + + + + + diff --git a/.zenodo.json b/.zenodo.json index 5ee56bb..5177379 100644 --- a/.zenodo.json +++ b/.zenodo.json @@ -4,12 +4,12 @@ "creators": [ { "name": "Van den Berg, Jur", - "affiliation": "University of North Carolina at Chapel Hill", + "affiliation": "University of North Carolina at Chapel Hill" }, { "name": "Snape, Jamie", "affiliation": "University of North Carolina at Chapel Hill", - "orcid": "0000-0002-3326-9765", + "orcid": "0000-0002-3326-9765" }, { "name": "Guy, Stephen J.", diff --git a/CPPLINT.cfg b/CPPLINT.cfg index b266b18..cf1abfa 100644 --- a/CPPLINT.cfg +++ b/CPPLINT.cfg @@ -37,5 +37,7 @@ set noparent filter=-build/header_guard +filter=-build/include_what_you_use +filter=-whitespace/indent_namespace linelength=80 From 5f4da6ce1813807b8be4fd580886e435304755aa Mon Sep 17 00:00:00 2001 From: Jamie Snape Date: Tue, 14 Apr 2026 21:25:47 -0400 Subject: [PATCH 2/2] docs: add ROS package manifest and quality declaration Signed-off-by: Jamie Snape --- .gitattributes | 1 + QUALITY_DECLARATION.md | 269 +++++++++++++++++++++++++++++++++++++++++ package.xml | 60 +++++++++ 3 files changed, 330 insertions(+) create mode 100644 QUALITY_DECLARATION.md create mode 100644 package.xml diff --git a/.gitattributes b/.gitattributes index e442f1e..edc26bf 100644 --- a/.gitattributes +++ b/.gitattributes @@ -57,6 +57,7 @@ *.md text diff=markdown whitespace-md *.pc.in text whitespace-2 *.txt text +*.xml text *.yaml text whitespace-2 *.yml text whitespace-2 diff --git a/QUALITY_DECLARATION.md b/QUALITY_DECLARATION.md new file mode 100644 index 0000000..70dcf79 --- /dev/null +++ b/QUALITY_DECLARATION.md @@ -0,0 +1,269 @@ + + +# `AVO2 Library` Quality Declaration + +The package `AVO2 Library` claims to be in the **Quality Level 2** category. + +Below are the rationales, notes, and caveats for this claim, organized by each +requirement listed in the Package Requirements for Quality Level 2 in +[REP-2004](https://www.ros.org/reps/rep-2004.html). + +## Version Policy [1] + +### Version Scheme [1.i] + +`AVO2 Library` uses [Semantic Versioning 2.0.0](https://semver.org/), and is +at version `1.0.1`. The version is declared in `CMakeLists.txt` and +`MODULE.bazel`. + +### Version Stability [1.ii] + +`AVO2 Library` is at a stable version (`1.0.1`), which is greater than +`1.0.0`. + +### Public API Declaration [1.iii] + +The public API of `AVO2 Library` is the set of symbols declared in +[`src/AVO.h`](src/AVO.h). This header aggregates the public interfaces of +`Simulator`, `Vector2`, and `Line`. Internal implementation details in +`Agent` and `KdTree` are not part of the public API. + +### API Stability Within a Released Version [1.iv] + +The public API is stable across patch and minor versions. Breaking API changes +are only introduced in new major versions. + +### ABI Stability Within a Released Version [1.v] + +ABI compatibility is maintained across patch versions within the same +`major.minor` release series. New major or minor versions may introduce +ABI-breaking changes. + +## Change Control Process [2] + +### Change Requests [2.i] + +All changes to `AVO2 Library` are submitted through pull requests on +[GitHub](https://github.com/snape/AVO2). Direct commits to the `main` branch +are not permitted outside of automated tooling. + +### Contributor Origin [2.ii] + +All contributors must sign off on their commits using the +[Developer Certificate of Origin (DCO)](https://developercertificate.org/), +enforced via the DCO GitHub App on every pull request. + +### Peer Review Policy [2.iii] + +As a single-maintainer project, all changes are reviewed by the primary +maintainer [@snape](https://github.com/snape) before merging. + +### Continuous Integration [2.iv] + +CI is performed via GitHub Actions on every push and pull request to `main`, +and on a daily schedule: + +- [`.github/workflows/ci.yml`](.github/workflows/ci.yml): builds and tests + with both CMake and Bazel on AlmaLinux, Alpine, Arch Linux, Fedora, + openSUSE, and Ubuntu (amd64 and arm64), and macOS (arm64). CMake builds + enable `BUILD_TESTING`, `ENABLE_HARDENING`, `ENABLE_OPENMP`, and + `WARNINGS_AS_ERRORS`. +- [`.github/workflows/codeql.yml`](.github/workflows/codeql.yml): runs GitHub + CodeQL semantic code analysis for C++ on a weekly schedule. + +### Documentation Policy [2.v] + +Changes are documented through commit messages and pull request descriptions +on GitHub. + +## Documentation [3] + +### Feature Documentation [3.i] + +All features of `AVO2 Library` are documented in the Doxygen markup within +[`src/AVO.h`](src/AVO.h) and related headers, including a usage guide, +parameter overview, and example code. An annotated example program +([`examples/Circle.cc`](examples/Circle.cc)) demonstrates typical usage +patterns covering agents and step-wise simulation. + +### Public API Documentation [3.ii] + +All public API elements are documented with Doxygen markup. HTML documentation +is generated from the source headers using `cmake -DBUILD_DOCUMENTATION=ON` +and installed with the library. + +### License [3.iii] + +Source code is licensed under the +[Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0). +Documentation is licensed under the +[Creative Commons Attribution-ShareAlike 4.0 International (CC-BY-SA-4.0)](https://creativecommons.org/licenses/by-sa/4.0/) +Public License. + +The project uses the [REUSE Specification](https://reuse.software/) for license +compliance. Every source file contains machine-readable SPDX license and +copyright headers, and license texts are provided in the [`LICENSES/`](LICENSES/) +directory. License compliance is verified by the `reuse` pre-commit hook. + +### Copyright Statement [3.iv] + +Copyright is held by the University of North Carolina at Chapel Hill. All +source files include the SPDX copyright notice: + +``` +SPDX-FileCopyrightText: 2010 University of North Carolina at Chapel Hill +``` + +### Quality Declaration [3.v] + +This document is the quality declaration for `AVO2 Library` and is linked from +the project README. + +## Testing [4] + +### Feature Testing [4.i] + +A system-level simulation scenario forms the test suite, run via `ctest` +(CMake) and `bazel test` (Bazel): + +- **Circle**: 250 agents initially distributed on a circle moving to their + antipodal positions. + +This scenario exercises all documented features of the library, including +agent management, the k-D tree spatial index, and step-wise simulation. + +### Public API Testing [4.ii] + +The simulation scenario exercises all major public API functions of +`Simulator`, `Vector2`, and `Line`. Dedicated unit tests for individual API +functions are not currently present. + +### Coverage [4.iii] + +Code coverage is not currently tracked. The simulation scenario provides +broad functional coverage of the library, but no formal coverage measurement +or policy is in place. This is a known gap relative to Quality Level 2 +requirements. + +### Performance [4.iv] + +No formal performance regression tests are in place. The simulation scenario +implicitly exercises performance characteristics of the library (e.g., the +Circle scenario with 250 agents), but no automated performance benchmarks are +run in CI. + +### Linters and Static Analysis [4.v] + +The following linters and static analysis tools are enforced, with all warnings +treated as errors in CI: + +- **clang-format**: code formatting enforced via [`.clang-format`](.clang-format) + (Google style with `PointerAlignment: Right`) +- **clang-tidy**: static analysis via [`.clang-tidy`](.clang-tidy), enabling + `bugprone-*`, `cert-*`, `clang-analyzer-*`, `cppcoreguidelines-*`, + `google-*`, `performance-*`, `portability-*`, `readability-*`, and + `openmp-*` checks, with `WarningsAsErrors: '*'` +- **cpplint**: Google C++ style enforcement via [`CPPLINT.cfg`](CPPLINT.cfg) +- **buildifier**: Bazel file formatting via [`.buildifier.json`](.buildifier.json) +- **CodeQL**: GitHub's semantic code analysis for C++ via + [`.github/workflows/codeql.yml`](.github/workflows/codeql.yml) +- **pre-commit hooks**: `codespell` (spell checking), `yamllint`, `actionlint` + (workflow validation), REUSE compliance, case-conflict detection, and + trailing-whitespace removal via [`.pre-commit-config.yaml`](.pre-commit-config.yaml) + +## Dependencies [5] + +### Direct Runtime ROS Dependencies [5.i] + +None. + +### Optional Direct Runtime ROS Dependencies [5.ii] + +None. + +### Direct Runtime non-ROS Dependencies [5.iii] + +- **C++ Standard Library**: provided by the compiler toolchain (GCC, Clang, or + MSVC). This is a de facto standard with no quality level concerns. +- **OpenMP** (optional): a widely-adopted, ISO-standardized API for shared-memory + parallel computing, available in all major compiler toolchains. Enabling + OpenMP parallelizes simulation steps across available processors. + +## Platform Support [6] + +`AVO2 Library` is built and tested continuously via GitHub Actions on the +following platforms: + +| Platform | Architecture | Build System | +|----------------|--------------|--------------| +| AlmaLinux 10 | amd64 | CMake, Bazel | +| Alpine Linux | amd64 | CMake, Bazel | +| Arch Linux | amd64 | CMake, Bazel | +| Fedora | amd64 | CMake, Bazel | +| openSUSE Leap | amd64 | CMake, Bazel | +| Ubuntu | amd64, arm64 | CMake, Bazel | +| macOS | arm64 | CMake, Bazel | + +## Security [7] + +### Vulnerability Disclosure Policy [7.i] + +The security policy is documented in +[`.github/SECURITY.md`](.github/SECURITY.md). Vulnerability reports should be +sent to [geom@cs.unc.edu](mailto:geom@cs.unc.edu). The current release is +supported with security updates when practical. diff --git a/package.xml b/package.xml new file mode 100644 index 0000000..d9271b4 --- /dev/null +++ b/package.xml @@ -0,0 +1,60 @@ + + + + + avo2 + 1.0.1 + + Reciprocal Collision Avoidance with Acceleration-Velocity Obstacles + + + Jamie Snape + + Apache-2.0 + + https://gamma.cs.unc.edu/AVO/ + https://github.com/snape/AVO + + Jur van den Berg + Jamie Snape + Stephen J. Guy + Dinesh Manocha + + cmake + + + cmake + +