IRT (Indirect Ray Tracing)

88.9% of first-parent commits in 12 months came through PRs, but only 38.9% of merged PRs had a review by someone other than the author; branch protection requires status checks but no approving review.

Gaps to the next level

• Fewer than 50% of merged PRs are reviewed by a non-author (e.g.
• Branch protection on main requires no approving review and is not enforced for admins.
• No CODEOWNERS file.

Actions

• medium S Add required_pull_request_reviews with one approval to the main branch protection and enable enforce_admins.
• medium S Add .github/CODEOWNERS naming at least two reviewers for source/ and include/.

linux-eic-shell.yml builds and installs with GCC and Clang on every PR and push and these jobs are required checks, but there are no tests to run and only 61.9% of recent default-branch runs succeeded.

Gaps to the next level

• CI runs no tests; the build step is cmake --build and cmake --install only.
• The clang-tidy job failed on every main push from 2026-01-25 to 2026-05-17 (8 consecutive runs).
• No integration or downstream check (e.g. building EICrecon's RICH-IRT plugin against the new build).

Actions

• high S Add a ctest --test-dir build --output-on-failure step to the build job once tests exist (see eng.testing).
• medium M Add a job that builds EICrecon with -DIRT2_ROOT pointing at the installed artifact in eic_xl:nightly.

The repository contains no test files, no test framework and no enable_testing(); issue #37 ("Unit testing") has been open since 2023-06.

Gaps to the next level

• No unit tests for the surface intersection, ray-tracing or reconstruction algorithms.
• No regression test against reference PID outputs.

Actions

• high M Add Catch2 unit tests (registered with ctest) for SphericalSurface, FlatSurface and the IRT ray-tracing solution.
• high M Add an end-to-end test that runs ReconstructionFactory on a small stored event file and checks the PID result.

.clang-tidy is applied to changed files on every PR as a required check and the library builds with -Wall and has sanitizer options, but no formatter is configured (FormatStyle: none) and clang-tidy findings do not fail CI.

Gaps to the next level

• No .clang-format or other formatter, and no format check in CI or pre-commit.
• The sanitizer options exist but no CI job enables them.

Actions

• medium S Add .clang-format and a .pre-commit-config.yaml with the clang-format hook, and enable pre-commit.ci.

CMake builds and installs libIRT2 with an exported IRT2Config.cmake, but the standard is set by overwriting CMAKE_CXX_FLAGS with a C++11 fallback although the code uses C++17, and a process-wide CherenkovDetectorCollection::m_Instance singleton holds global state.

Gaps to the next level

• C++17 is not required (CMAKE_CXX_STANDARD unset; falls back to -std=c++11) and user CMAKE_CXX_FLAGS are discarded.
• Global singleton state in CherenkovDetectorCollection.
• The EVALUATION subproject links a non-existent IRT target and the retired DD4pod library, and the build adds ${CMAKE_INSTALL_PREFIX}/include to include paths.

Actions

• medium S Replace the flag logic in CMakeLists.txt with set(CMAKE_CXX_STANDARD 17) and CMAKE_CXX_STANDARD_REQUIRED ON.
• medium S Remove or port evaluation/ and drop ${CMAKE_INSTALL_PREFIX}/include from include_directories.

The README has CMake build and run commands, but it opens with "THIS README is OBSOLETE" and describes the retired ATHENA, eicd and jug_xl workflow; IRT2, its dependencies and the JSON configuration are not documented.

Gaps to the next level

• No current installation instructions with dependency versions (ROOT 6, optional nlohmann_json 3.11.2) or an eic-shell route.
• No runnable quick-start example for the IRT2 API; CMake options and the JSON configuration format are undocumented.

Actions

• high S Rewrite README.md for IRT2 with eic-shell and from-source builds, dependency versions, CMake options and a minimal usage example.

Public headers carry scattered inline comments and the README introduction describes the mass-hypothesis approach, but there is no Doxygen or other generated API reference and no architecture overview of IRT2.

Gaps to the next level

• Most public classes and methods (e.g. ReconstructionFactory, CherenkovDetectorCollection) have no API comments.
• No generated API docs and no architecture document.

Actions

• medium M Add a Doxyfile and docs/architecture.md describing the detector, radiator, surface and reconstruction classes and their data flow.

Only the eic organization PR template and issue templates apply; there is no CONTRIBUTING file describing setup, building, conventions or the PR process.

Gaps to the next level

• No CONTRIBUTING file covering eic-shell setup, build, conventions and PR process.
• No newcomer issues labeled (good first issue label exists but is unused).

Actions

• medium S Add CONTRIBUTING.md covering eic-shell setup, CMake build, clang-tidy expectations and the PR/release process.

No issues were opened in 12 months, and all 6 open issues are older than one year with five of them never answered; non-bot PRs merge in a median of 0.45 days, but PR #41 has been open since 2024-05.

Gaps to the next level

• All open issues are older than one year (#4,
• Three open PRs are older than 90 days without review.

Actions

• medium S Triage the six open issues and three stale PRs, labeling or closing each.

Three authors from two email domains committed in 24 months, with no new authors in 12 months and no merged PRs from outside the maintainer group.

Gaps to the next level

• Fewer than 4 active authors in 24 months.
• No external PRs merged in 12 months.

Actions

• high M Present IRT2 at an ePIC PID or reconstruction meeting and recruit a co-developer from a third institution.

The 50% bus factor is 2 (top author 44.4%) with four reviewers and four mergers, and two people made releases, but no CODEOWNERS or maintainer list in the repository names owners.

Gaps to the next level

• No maintainer list or CODEOWNERS names at least two people.

Actions

• high S Add .github/CODEOWNERS naming two owners for the library code and the build/CI files.

Changes are discussed in public PRs, but neither the README nor a CODEOWNERS file names the maintainers, and there is no decision process, roadmap or milestone.

Gaps to the next level

• Maintainers are not identified in the repository.
• No documented decision process, maintainer path, roadmap or milestones.

Actions

• high S Add a "Maintainers" section to README.md naming the maintainers and the owning ePIC group.

The eic organization issue-template configuration links the ePIC Mattermost and meetings for questions, but no code of conduct applies to the repository or the organization.

Gaps to the next level

• No code of conduct with a reporting contact.

Actions

• high S Add CODE_OF_CONDUCT.md linking the ePIC code of conduct and a reporting contact, or add it once in eic/.github.

The eic-spack irt2 recipe provides 2.2.3, added the day after the release, and eic-shell ships irt2 2.2.3 alongside irt 1.0.10; the collector checked only the irt recipe, hence latest_release_packaged = false.

Ten releases in 24 months each have generated release notes, but no version scheme is documented and the CMake project version (2.2.0) does not match the released tag v2.2.3.

Gaps to the next level

• No documented version scheme, including how the parallel 1.0.x (v1 branch) and 2.x lines are numbered.
• project(IRT2 VERSION ...) is not updated per release, so IRT2ConfigVersion.cmake reports 2.2.0.

Actions

• medium S State SemVer and the 1.x/2.x maintenance policy in README.md and bump project(IRT2 VERSION ...) in each release PR.

ROOT 6 and nlohmann_json 3.11.2 are declared with minimum versions and Dependabot updates GitHub Actions, but the optional evaluation/ build depends on the undeclared, retired DD4pod, and DrcPidFast is copied code without version or license.

Gaps to the next level

• evaluation/ uses DD4pod and EDM4eic headers without find_package and links a non-existent IRT target.
• DrcPidFast is copied third-party code with no version or provenance beyond an author line.

Actions

• medium S Delete evaluation/ (or port it to EDM4hep via find_package(podio)/find_package(EDM4hep)) and record the origin and version of DrcPidFast.

CI builds in the unpinned eic_xl:nightly image, and the README describes an obsolete jug_xl setup; no eic-shell version is documented for any release.

Gaps to the next level

• No documented eic-shell version or machine-readable environment tied to releases.
• Configuration and calibration inputs used for outputs are not recorded with the output.

Actions

• medium S Document in README.md the eic-shell release each IRT2 version is built and validated in.

CI builds with GCC and Clang on Linux x86_64 and no site paths are present, but no tests run on either toolchain, so the two-configuration condition is met for builds only.

Gaps to the next level

• No tests run on any configuration.
• Only Linux x86_64 is built.

Actions

• medium S Run the new ctest suite in each matrix entry of linux-eic-shell.yml.

The library is a supported component that EICrecon and the epic dRICH/pfRICH geometry reuse, but in-tree readers still use the retired dd4pod format and a private Geant4 event tree instead of EDM4hep, without documented justification.

Gaps to the next level

• evaluation/ reads dd4pod collections rather than EDM4hep/podio.
• The standalone GeantImport event tree format is not justified against EDM4hep in the documentation.

Actions

• medium S Remove the dd4pod-based evaluation/ and document why the standalone CherenkovEvent tree is needed alongside EDM4hep input.

Geometry, events and calibrations are read and written as ROOT-dictionary-serialized IRT classes (tree t, branch e) and a JSON configuration, with no schema documentation; EDM4eic output is produced by EICrecon, not by IRT.

Gaps to the next level

• The ROOT object layout of CherenkovDetectorCollection/CherenkovEvent and the JSON configuration keys are undocumented.

Actions

• medium S Document the CherenkovDetectorCollection file layout and the JSON configuration keys in docs/formats.md.

CI builds in eic_xl:nightly through eic/run-cvmfs-osg-eic-shell on every PR, but the README documents only the obsolete jug_xl/ATHENA setup and no stable eic-shell release is tested.

Gaps to the next level

• Building and using IRT2 in current eic-shell is not documented.
• No tests run in the eic container.

Actions

• medium S Add an eic-shell build section to README.md and run the ctest suite in the eic_xl:nightly job.

The library builds against current eic_xl:nightly and eic-shell ships the latest release, which EICrecon requires (IRT2_VERSION_MIN 2.2.0); the in-tree evaluation code still targets the retired dd4pod and eicd stack.

Gaps to the next level

• Code paths for the retired dd4pod data model remain in evaluation/ and the README.

Actions

• low S Remove the dd4pod/eicd-era evaluation/ code and README sections.

LGPL-3.0 is detected and compatible with ROOT and nlohmann_json, but the license is not stated in CMake or package metadata and the copied DrcPidFast code carries no license statement.

Gaps to the next level

• License not declared in package metadata.
• Third-party DrcPidFast code has no recorded license.

Actions

• medium S Add LICENSE.spdx or a license("LGPL-3.0-or-later") entry in the eic-spack irt2 recipe, and record the license of DrcPidFast.

There is no CITATION.cff, Zenodo metadata, DOI, reference publication or author list.

Gaps to the next level

• No citation metadata or author list.

Actions

• high S Add CITATION.cff with the authors and enable the Zenodo-GitHub integration for release DOIs.

IRT ships in eic-shell and is a dependency of EICrecon, whose RICH-IRT plugin uses IRT2, and the epic dRICH and pfRICH geometry plugins build IRT2 optics; it is part of the ePIC reconstruction chain.

Maintainers are identifiable through the eic-spack recipe and commit email domains, but the repository names no owning ePIC working group, institutional commitment or funding.

Gaps to the next level

• No owning ePIC body, institutional commitment or funding acknowledgement documented.

Actions

• medium S State the owning ePIC PID/reconstruction working group and maintainer institutions in README.md.