EICrecon

All first-parent commits arrive through PRs, but 49.2% of merged human PRs in 12 months had a review from someone other than the author, below the 50% needed for level 2.

Gaps to the next level

• Fewer than 50% of merged PRs in 12 months were reviewed by a non-author; the ruleset requiring one approval exists only since 2026-09-15.
• No CODEOWNERS file.

Actions

• high S Keep the main ruleset's one-approval requirement active so that at least 50% (then 90%) of merged PRs carry a non-author review in the next 12-month window.

linux-eic-shell.yml builds and runs ctest on every PR, merge-queue entry and push to main in eic-shell (GCC and Clang, nightly and two stable releases), required status checks gate the merge queue, full simulation-plus-reconstruction jobs and an eic_container trigger provide integration checks, and 92% of default-branch runs succeed.

Catch2 unit tests exist for 22 of about 87 algorithm sources, and the per-library coverage posted by CI ranges from 2.9% (reco) to 66.7% (pid_lut), so unit tests cover a minority of algorithms; end-to-end reconstruction jobs and capybara comparisons against the base-branch output do run in CI.

Gaps to the next level

• Unit tests cover a minority of algorithms (coverage below 30% in 6 of 9 algorithm libraries, 2.9% in reco).
• Only 14.5% of merged PRs touch test files.
• tracking_test, track_propagation_test and geometry_navigation_test are not added in src/tests/CMakeLists.txt.

Actions

• medium L Add Catch2 tests in src/tests/algorithms_test/ for the untested algorithms in src/algorithms/reco and src/algorithms/tracking until each algorithm library reports coverage above 50%.
• medium S Add a PR-template checkbox and review rule requiring a unit test for every new or changed algorithm.

clang-format, codespell and cmake-lint run through pre-commit.ci, clang-tidy and IWYU run on changed files in every PR, ASan/UBSan/TSan builds run in CI, and builds use -Werror -Wall -Wextra; clang-tidy findings are advisory and deprecation warnings are exempted from -Werror.

Gaps to the next level

• .clang-tidy sets no WarningsAsErrors, so clang-tidy findings neither fail CI nor are tracked to zero.
• -Wno-error=deprecated-declarations is applied repository-wide in the CI matrix.

Actions

• medium M Set WarningsAsErrors in .clang-tidy for the enabled check groups, or publish the clang-tidy warning count on main and drive it to zero.
• low M Remove -Wno-error=deprecated-declarations from the CI matrix once the Acts deprecations are resolved.

Code is split into algorithms, factories, services and detector plugins built with CMake (C++20) and exported via EICreconTargets and EICreconConfig.cmake, with parameters exposed through JANA -P options; every header is installed with no public/internal split and there is no architecture overview.

Gaps to the next level

• All headers are installed (cmake/jana_plugin.cmake L168-L171); no public API is separated from internals.
• No architecture overview of the plugin, factory and algorithm layers.
• Detector calibration defaults are compiled into src/detectors/* plugins.

Actions

• medium S Write docs/design/architecture.md describing the algorithms/factories/services/detectors layers and the data flow, and link it from docs/_sidebar.md.
• low M Install only headers of the algorithm interfaces and configs intended for downstream use, and mark the rest internal.

README and the hosted docs give the eic-shell build route and a tutorial that runs eicrecon on a sample file, and flags are listed on the site, but the from-source instructions list stale versions that contradict the build (JANA v2.0.7, ACTS v19.9.0, -DCMAKE_CXX_STANDARD=17 against the C++20 minimum).

Gaps to the next level

• docs/get-started/manual-build.md dependency versions do not match the minimums in CMakeLists.txt and omit algorithms, onnxruntime, FastJet and IRT2.
• docs/howto/full_chain_simulation.md still refers to athena.xml and Juggler.

Actions

• medium S Regenerate the dependency list in docs/get-started/manual-build.md from the *_VERSION_MIN values in CMakeLists.txt and remove the C++17 flags.
• medium S Update or remove docs/howto/full_chain_simulation.md so the quick start uses npsim and eicrecon with a current input file.

Doxygen is generated and published from main to the docs site, and design pages cover tracking, logging and CMake, but 42 of 169 algorithm headers carry Doxygen-style comments and there is no architecture overview.

Gaps to the next level

• Most public algorithm headers have no Doxygen comments on classes, configs or methods.
• No architecture overview page.

Actions

• medium L Add Doxygen comments to every src/algorithms/*/*.h class and *Config.h member, and set WARN_IF_UNDOCUMENTED in the Doxyfile to track the remainder.
• medium S Add docs/design/architecture.md with a component and data-flow diagram.

CONTRIBUTING.md covers the PR process, review criteria and coding conventions, the tutorials and AGENTS.md cover eic-shell setup, building and ctest, a PR template and a devcontainer exist; newcomer issues have not been labeled or closed since 2024 and there are no issue templates.

Gaps to the next level

• The two open good first issue issues (#400,
• CONTRIBUTING.md does not itself describe build and ctest steps; no issue templates.
• docs/tutorial/04-contributing.md links GitHub Discussions, which are disabled.

Actions

• medium S Label at least five current issues good first issue and add .github/ISSUE_TEMPLATE/ bug and feature templates.
• low S Add a "Build and test" section to CONTRIBUTING.md covering eic-shell, cmake and ctest --test-dir build.

Median first response is 5.1 days, but 139 of 197 open issues are older than one year and 4.8% of new issues are labeled.

Gaps to the next level

• More than half of open issues (70.6%) are older than one year.
• Most new issues are not labeled or otherwise triaged.

Actions

• medium M Review the 139 issues older than one year and close or label each, and apply a topic: label to every new issue at triage.

34 authors from 10 e-mail domains committed in 24 months with 10 new authors in 12 months, but no merged PR in 12 months came from outside the eic organization membership, and the four fork PRs merged in 24 months were by members.

Gaps to the next level

• No PRs from contributors outside the maintainer organization were merged in 12 months.

Actions

• medium S Document in CONTRIBUTING.md how non-ePIC contributors can submit fork PRs that pass CI, and merge at least one such PR.

One author wrote 51.8% of commits in 24 months; review and merging are spread across 24 reviewers and 23 mergers, but no CODEOWNERS or maintainer list names owners.

Gaps to the next level

• Bus factor (50%) is 1.
• No CODEOWNERS or maintainer list.

Actions

• high S Add .github/CODEOWNERS naming at least two owners for each of src/algorithms/*, src/factories, src/services and .github/.

CONTRIBUTING.md assigns review to an ePIC software review team and asks contributors to consult the reconstruction and simulation working groups, and decisions are visible in PRs; no maintainers are named, there is no maintainer path, and milestones stopped in 2024.

Gaps to the next level

• No document naming maintainers, who decides, or how to become a reviewer or maintainer.
• Milestones last used in 2024; no public roadmap.

Actions

• high S Add GOVERNANCE.md naming the maintainers by role, the owning ePIC working group, the decision process and the path to reviewer and maintainer.

CONTRIBUTING.md links the ePIC code of conduct and a review-team contact, but the public code of conduct page names no reporting contact, and GitHub Discussions, linked from the tutorial, are disabled.

Gaps to the next level

• The linked code of conduct has no public reporting contact.
• No "Getting help" section naming a user support channel.

Actions

• high S Add a CODE_OF_CONDUCT.md that links the ePIC code and gives a public reporting contact, and a README "Getting help" section linking the ePIC Mattermost reconstruction channel or the issue tracker.

eic-spack carries a recipe that provides the latest release 1.42.0, and eic-shell ships that version.

43 releases in 24 months all have generated notes grouped by topic, but no version scheme is documented and there is no changelog, deprecation policy or release workflow.

Gaps to the next level

• The version scheme (vMAJOR.MINOR.PATCH tags) is not documented.
• Release notes do not flag breaking changes or give migration notes.

Actions

• medium S State in README.md that releases follow SemVer and define what bumps MAJOR (for example renamed or removed output collections).

Most dependencies are declared with minimum versions in CMakeLists.txt, but Microsoft.GSL, nlohmann_json, Boost and cppzmq are found without version constraints; Dependabot covers GitHub Actions only, 37 uses: refs point to @main, and there is no SECURITY.md.

Gaps to the next level

• Microsoft.GSL, nlohmann_json, Boost and cppzmq have no minimum version.

Actions

• medium S Add minimum versions to the find_package calls for Microsoft.GSL, nlohmann_json, Boost and cppzmq in CMakeLists.txt and the src/services/*/CMakeLists.txt files.

The environment is machine-readable (eic-shell images, devcontainer on eic_ci:nightly) and its use is documented, but output files do not record the EICrecon version, parameter set or random seed.

Gaps to the next level

• The podio writer stores no EICrecon version, configuration parameters or seed in the output metadata.

Actions

• medium M Write the EICrecon version and the full JANA parameter set (including the UniqueIDGenSvc seed) into a podio metadata frame in JEventProcessorPODIO::Finish.

CI builds and tests with GCC and Clang on Linux x86_64 and there are no site-specific paths; no aarch64 or macOS job exists and accelerator use is not documented.

Gaps to the next level

• No CI job on a second architecture (aarch64) or OS.
• HTC/OSG usage and accelerator support (or why not) are not documented.

Actions

• medium M Add an ubuntu-24.04-arm build-and-ctest job in eic-shell to linux-eic-shell.yml.

EICrecon builds on JANA2, algorithms, podio, EDM4eic, DD4hep and ACTS, but a 600-line helix propagation and pairing code derived from STAR (Helix.cc) runs secondary vertexing in parallel to the ACTS-based SecondaryVertexFinder without documented justification.

Gaps to the next level

• Helix-based secondary vertexing reimplements track propagation and vertexing available in ACTS, with no documented reason.

Actions

• medium S Document in docs/design/tracking.md why SecondaryVerticesHelix is kept alongside the ACTS vertexer, or replace it with ACTS propagation and vertex fitting.

Inputs are EDM4hep and outputs EDM4eic podio files, a two-stage CI job re-reads EICrecon output, and CI reads outputs with uproot; the podio file-version check is logged but its failure is commented out.

Gaps to the next level

• The version mismatch check in JEventSourcePODIO.cc does not throw (FIXME), and no EDM4eic version check on read.

Actions

• medium S Re-enable the exception in JEventSourcePODIO.cc L139-L143 and add an EDM4eic/EDM4hep datamodel version check against the file metadata.

The eic-shell build is documented, and CI builds and tests in eic_xl nightly and in the pinned 26.02.0-stable and 26.04.1-stable releases through eic/run-cvmfs-osg-eic-shell.

Minimum versions (Acts 44, podio 1.3, EDM4eic 8.7, DD4hep 1.21) are satisfied by current eic-shell (Acts 46.8.1, podio 1.8, EDM4eic 8.10.0) and nightly CI passes, but Acts deprecation warnings are exempted from -Werror, so deprecated APIs remain in use.

Gaps to the next level

• Code uses Acts APIs deprecated in Acts v46.

Actions

• medium M Migrate the remaining deprecated Acts seeding calls and drop -Wno-error=deprecated-declarations from linux-eic-shell.yml.

GitHub detects LGPL-3.0 and 374 files carry LGPL-3.0-or-later SPDX headers, but NOTICE.md declares the repository public domain except where a LICENSE.md exists (only src/algorithms), and STAR-derived Helix.h/.cc have license "TBD".

Gaps to the next level

• NOTICE.md (public domain) contradicts LICENSE.LGPL3 and the SPDX headers.
• Third-party STAR code is included without a recorded license.

Actions

• high S Replace NOTICE.md with a statement that the repository is LGPL-3.0-or-later and that contributions are accepted under it (inbound = outbound).
• high S Determine the license of the STAR-derived src/algorithms/reco/Helix.*, record it in their SPDX headers, or replace the code.

The Zenodo-GitHub integration issues a DOI per release under concept DOI 10.5281/zenodo.7942531 with a 27-creator list; there is no CITATION.cff and no reference publication.

Gaps to the next level

• No reference publication or software paper is cited.
• The Zenodo record credits 27 creators against 65 git authors; no .zenodo.json or CITATION.cff curates the list.

Actions

• low S Add CITATION.cff and .zenodo.json with the full contributor list and a preferred-citation entry for an EICrecon reference publication.

EICrecon ships in eic-shell, is the ePIC reconstruction used by detector benchmarks and tutorials, and is a dependency of juggler in eic-spack.

CONTRIBUTING.md places development under the ePIC reconstruction and simulation working groups and the ePIC software review team; there is no documented multi-institution maintenance commitment or succession plan.

Gaps to the next level

• No documented multi-institution maintenance commitment or succession plan.

Actions

• medium S State in README.md the owning ePIC working group, the maintaining institutions, and what happens when a maintainer leaves.