Skip to content

QUALITY_DECLARATION.md

Latest commit

 

History

History
269 lines (186 loc) · 9.49 KB

QUALITY_DECLARATION.md

File metadata and controls

269 lines (186 loc) · 9.49 KB

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.

Version Policy [1]

Version Scheme [1.i]

AVO2 Library uses Semantic Versioning 2.0.0, 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. 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. 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), 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 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: 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: 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 and related headers, including a usage guide, parameter overview, and example code. An annotated example program (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. Documentation is licensed under the Creative Commons Attribution-ShareAlike 4.0 International (CC-BY-SA-4.0) Public License.

The project uses the REUSE Specification for license compliance. Every source file contains machine-readable SPDX license and copyright headers, and license texts are provided in the 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 (Google style with PointerAlignment: Right)
  • clang-tidy: static analysis via .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
  • buildifier: Bazel file formatting via .buildifier.json
  • CodeQL: GitHub's semantic code analysis for C++ via .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

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. Vulnerability reports should be sent to geom@cs.unc.edu. The current release is supported with security updates when practical.