ePIC geometry

98.7% of first-parent commits in 12 months came through PRs and 97.3% of merged PRs had a non-author review; the default branch is protected and CONTRIBUTING.md and a PR template document the one-reviewer requirement.

linux-eic-shell.yml builds on every PR, merge-group and push to main with geometry, overlap, npsim and EICrecon jobs and required status checks, but only 68% of recent default-branch runs succeeded, below the 80% needed for level 2.

Gaps to the next level

• Default-branch success rate is 68%; recent failures are npsim-dis jobs timing out on remote XRootD input (TNetXNGFile::Open socket timeout) and a dawn-view-slices job.

Actions

• high S Cache the npsim-dis HepMC3 input files with actions/cache (or retry the XRootD read) in .github/workflows/linux-eic-shell.yml so remote-server timeouts no longer fail main.

Every PR builds all 77 configurations (including per-subsystem *_only configurations) and runs checkGeometry, g4GeometryScan, TGeo and Geant4 overlap checks and npsim/EICrecon end-to-end jobs with capybara comparisons against main; coverage is not measured and 1.8% of merged PRs touch test files.

Gaps to the next level

• No test coverage of the detector plugins is measured or published.
• Only 1.8% of merged PRs in 12 months touch test files; there are no per-plugin tests of constructed dimensions or parameters.
• Capybara comparisons produce reports but do not fail CI on differences.

Actions

• medium M Add a gcov/Codecov job that runs the per-configuration checkGeometry loop on a coverage build and publishes plugin coverage.
• medium M Add a scripted check (e.g. scripts/subdetector_tests/) that compares dumped constants or material scans against stored references and is required for PRs that change src/ or compact/.

clang-format and pre-commit hygiene hooks run through pre-commit.ci, xmllint and SPDX-header checks run on every PR, and non-Release builds use -Wall -Wextra -Werror -pedantic; no clang-tidy, cppcheck or sanitizer job runs.

Gaps to the next level

• No deeper static analysis (clang-tidy, cppcheck) or sanitizer build, although CMAKE_EXPORT_COMPILE_COMMANDS is set for clang-tidy.

Actions

• medium S Add a clang-tidy job on changed src/ files using the exported compile_commands.json from the eic-shell build.

Each detector is a DD4hep plugin in src/ configured by compact XML and YAML/Jinja2 configurations, built with CMake (C++17) and installed with a setup script; there is no exported CMake package config and no architecture documentation.

Gaps to the next level

• No install(EXPORT ...) or package config for downstream CMake consumers; consumers rely on thisepic.sh environment variables.
• The plugin, compact-file and configuration-template architecture is not documented (templates/README.md is 3 lines).

Actions

• medium M Add docs/architecture.md describing plugins, compact files, the Jinja2 configuration templates and the FileLoader, and install an epicConfig.cmake.

The README gives cmake build and thisepic.sh instructions and links a hosted geometry viewer, but names no dependencies or versions, does not describe the eic-shell route (it links retired eicweb tutorial and container pages), and has no runnable example.

Gaps to the next level

• Dependencies (DD4hep >= 1.27, ROOT, fmt, optional IRT2, jinja2) and versions are not listed in the README.
• No eic-shell quick start and no runnable example (e.g. an npsim or checkOverlaps command).
• Detector configurations and DETECTOR_CONFIG options are not documented for users.

Actions

• medium S Add an "Installation" README section naming dependencies with minimum versions and the eic-shell route (/opt/detector builds and source install/bin/thisepic.sh), and link the EIC geometry-development tutorial.
• medium S Add a quick-start example running npsim on epic_craterlake.xml and a table of the configurations in configurations/.

27 of 61 plugin sources carry Doxygen-style comments, but there is no Doxygen configuration, no generated API reference and no architecture overview.

Gaps to the next level

• No generated API documentation of plugin XML parameters.
• No architecture overview of how plugins, compact files and configuration templates fit together.

Actions

• medium M Add a Doxyfile and a job in linux-eic-shell.yml that publishes the generated plugin reference with the existing GitHub Pages artifacts site.

.github/CONTRIBUTING.md covers the PR process, review requirement and clang-format/no-warning conventions, and issue and PR templates exist, but it does not describe setting up the development environment or running the geometry checks locally.

Gaps to the next level

• CONTRIBUTING.md has no development-environment setup (eic-shell or the devcontainer) and no instructions for running checkGeometry/checkOverlaps locally.

Actions

• medium S Extend .github/CONTRIBUTING.md with eic-shell/devcontainer setup, the cmake build, and the checkGeometry and scripts/checkOverlaps.py commands CI runs.

Median first response is 1.6 days and PRs are reviewed, but 58 of 66 open issues are older than one year and 10% of new issues are labeled.

Gaps to the next level

• 88% of open issues are older than one year.
• 90% of new issues in 12 months are unlabeled; no triage process is documented.

Actions

• medium S Review the 58 open issues older than a year, close or label each with the existing topic: labels, and apply a topic label to every new issue.

35 authors from 9 e-mail domains committed in 24 months with 12 new authors in 12 months, but every non-bot PR merged in 24 months came from an eic organization member.

Gaps to the next level

• No merged PRs from contributors outside the eic organization membership.

Actions

• medium S Link the 15 good first issue issues from the README and CONTRIBUTING.md and review fork PRs from non-members.

The 50% bus factor is 2 with 17 reviewers and 14 mergers, but no CODEOWNERS or maintainer list names owners, and one person published all 24-month releases.

Gaps to the next level

• No CODEOWNERS or maintainer list naming at least two people.
• All releases in 24 months were made by one person and the release procedure is not documented.

Actions

• high S Add .github/CODEOWNERS assigning two owners per src//compact/ subsystem directory.
• high S Document the monthly release and backport procedure in RELEASING.md and have a second maintainer publish a release.

Maintainers can be identified only from LICENSE.spdx originators and the eic-spack recipe, and decisions are visible in PRs and linked weekly meetings, but there is no documented decision process or maintainer path, and milestones stopped in 2025.

Gaps to the next level

• No document states who decides, who the "core developers" in CONTRIBUTING.md are, or how to become one.
• Milestones are stale (latest open milestone 25.08.0).

Actions

• medium S Add GOVERNANCE.md naming the maintainers and core developers, the decision process, and the path to reviewer and maintainer.

The issue-template configuration links the EIC Mattermost and weekly Indico meetings for support, but no code of conduct applies at repository or organization level.

Gaps to the next level

• No code of conduct with a reporting contact.

Actions

• high S Add CODE_OF_CONDUCT.md (or link the ePIC collaboration code of conduct) with a reporting contact.

The eic-spack recipe provides 26.10.0 and was updated the day of the release, and the eic_xl environment builds epic release 26.10.0, earlier releases and main into eic-shell (the collector's in_eic_shell checks only the top-level spec list and reports false).

42 tags in 24 months with generated, categorized release notes on every release, but the YY.MM.N version scheme is not documented anywhere in the repository.

Gaps to the next level

• The CalVer scheme and patch/backport policy are not documented.
• No changelog with migration notes, no deprecation policy, and no release workflow.

Actions

• medium S State the YY.MM.patch CalVer scheme and the backport label policy in the README.

CMakeLists.txt requires DD4hep >= 1.27 and IRT2 >= 2.1.1, but fmt and the requirements.txt Python packages have no version constraints; Dependabot monitors only GitHub Actions.

Gaps to the next level

• find_package(fmt), ROOT (via dd4hep_add_plugin USES) and jinja2/jinja2-cli have no minimum versions.
• No SECURITY.md; several actions are referenced at @main.

Actions

• medium S Add minimum versions to find_package(fmt ...) and an explicit find_package(ROOT ...), and to the entries in requirements.txt.

The eic-shell images (.devcontainer on eic_ci:nightly, CI on eic_xl) are the machine-readable environment, installs record epic_version in compact/version.xml and DETECTOR_VERSION, external data are pinned to epic-data commits, and CI simulations fix seeds; CI tests only against nightly, and no release states its eic-shell version.

Gaps to the next level

• Release notes do not name the eic-shell release that ships or was used to validate each epic release.
• The README's container link points to the retired eicweb container page rather than current eic-shell instructions.

Actions

• medium S Add the validating eic_xl:<version>-stable tag to each release's notes and run the PR checks on that pinned image as well as nightly.

CI builds with GCC and Clang, no site-specific paths are present, and external data are fetched through a configurable DETECTOR_CACHE; all CI runs on Linux x86_64.

Gaps to the next level

• No aarch64 or macOS CI job, although thisepic.sh handles Darwin.
• Use on distributed HTC resources is not documented in the repository.

Actions

• medium S Add an ubuntu-24.04-arm build-and-checkGeometry job in linux-eic-shell.yml.

The geometry is DD4hep compact XML with DD4hep plugins, tracking surfaces and material maps use ACTS, and validation uses npsim, EICrecon and epic-capybara; the project is itself the geometry component that EICrecon, npsim and the benchmarks load.

The geometry is DD4hep compact XML and CI exports TGeo, GDML and STEP and writes EDM4hep simulation output; the geometry version is recorded but not checked, and there is no export round-trip test.

Gaps to the next level

• The epic_version constant is not checked by consumers or tests.
• No round-trip test that reloads exported GDML/TGeo and compares it to the DD4hep geometry.

Actions

• medium M Add a CI step that loads the exported TGeo file with uproot or ROOT and compares volume counts and material budget with the DD4hep geometry.

CI builds and tests in eic_xl:nightly through eic/run-cvmfs-osg-eic-shell, and the README points to the container image; the only stable-release job builds on 25.07.0-stable and no tests run against a stable release.

Gaps to the next level

• Tests run only on nightly; the 25.07.0-stable build is five eic-shell releases behind v26.10.0-stable and its artifact is not tested.

Actions

• medium S Move the stable build in linux-eic-shell.yml to the current eic_xl:<release>-stable and run check-geometry-configs and the overlap checks on it.

Every release ships in the current eic-shell, PR CI builds against nightly with -Werror (so deprecated-declaration warnings fail the build), and no open issue reports a stack incompatibility.

LGPL-3.0 is detected, LICENSE.spdx declares LGPL-3.0-or-later, and CI enforces SPDX headers on all sources; there are no documented contribution terms (DCO or inbound = outbound).

Gaps to the next level

• Contribution licensing terms are not documented.

Actions

• low S State in .github/CONTRIBUTING.md that contributions are accepted under LGPL-3.0-or-later (inbound = outbound) or require DCO sign-off.

CITATION.cff exists and the Zenodo-GitHub integration issues a DOI per release (concept DOI 10.5281/zenodo.16806749), but both credit only "EPIC Collaboration" and no author or contributor list is maintained.

Gaps to the next level

• No maintained author or contributor list in CITATION.cff, .zenodo.json or an AUTHORS file.

Actions

• medium S Add .zenodo.json and CITATION.cff author lists covering significant contributors, and add the concept DOI to the README and CITATION.cff.

Every epic release is built into eic-shell, the geometry is used by the ePIC simulation production and by detector benchmarks, and EICrecon and npsim load it.

The repository is in the eic organization, cites "EPIC Collaboration" as author and links ePIC computing meetings, but no document assigns maintenance to an ePIC working group or acknowledges funding.

Gaps to the next level

• No owning ePIC working group, institutional commitment or funding stated in README or CONTRIBUTING.md.

Actions

• medium S State in the README the ePIC working group responsible for the geometry and the maintainers' institutions.