eic-smear

Only 41% of first-parent commits in 12 months came from PRs; version bumps and code fixes are pushed directly, and the ruleset requires no approving review.

Gaps to the next level

• Fewer than 80% of default-branch changes in 12 months arrived through PRs.
• The master ruleset only blocks deletion and force-push and requests Copilot review; no human approval is required.

Actions

• medium S Add a pull_request rule with one required approving review to ruleset 10735385 so code fixes and version bumps go through PRs.

The single workflow builds and installs in the eic_xl nightly image on every PR and push to master (12 of 12 default-branch runs succeeded), but runs no tests.

Gaps to the next level

• CI runs no test suite or example; it only compiles and installs.

Actions

• medium S Add a step to .github/workflows/linux-eic-shell.yml that runs ctest (once tests exist) and a BuildTree/SmearTree/TreeToHepMC run on a small committed input file.

The repository contains no test files, no CTest registration and no test framework; no merged PR in 12 months touched tests.

Gaps to the next level

• No unit tests for the generator readers, Smear::Detector/Smearer classes or TreeToHepMC.
• The README says example files are included for testing, but none are in the repository.

Actions

• high M Add enable_testing() and a CTest test that runs BuildTree on a small committed generator text file per supported format and checks the event count.
• high S Add a test that converts a committed tree with TreeToHepMC and checks particle counts and cross-section units in the HepMC3 output.

-Wall -Wextra -pedantic are enabled and the README asks contributors to run a bundled copy of cpplint, but no formatter or linter runs in CI or pre-commit.

Gaps to the next level

• No formatter configuration and no linter enforced on PRs.

Actions

• medium S Add .clang-format (Google-based, matching the README conventions) and a .pre-commit-config.yaml with clang-format, enabled on pre-commit.ci.
• medium S Replace the vendored eicpy/cpplint.py with a CI job running upstream cpplint with the README filter on changed files.

Code is split into erhic, Smear and hadronic namespaces and installs an exported eicsmearConfig.cmake, but the declared language standard is C++11 and the eicpy scripts use Python 2 syntax.

Gaps to the next level

• Declared C++ standard is C++11 (cxx_std_11), below C++17.
• eicpy/*.py use Python 2 print statements; stale files (Forester.cxx.orig, *.betterbutdifferent) remain in the source tree.

Actions

• medium S Set target_compile_features(eicsmear PUBLIC cxx_std_17) (or higher) on all targets in CMakeLists.txt.
• low S Port eicpy/ to Python 3 or remove it, and delete the .orig and .betterbutdifferent files.

The README gives CMake build and run instructions, but its prerequisites (CMake 3.1, ROOT 6.10) disagree with CMakeLists.txt (3.10, 6.20), omit HepMC3 and zlib, and give no eic-shell route.

Gaps to the next level

• Dependencies and minimum versions in the README do not match the build files; HepMC3 and zlib are missing.
• No runnable example in the repository; the README one-liner uses an input file that is not included.
• Using the eic-shell installation is not documented.

Actions

• medium S Update the README "Prerequisites" to CMake >= 3.10, ROOT >= 6.20, HepMC3 and zlib, and add an "Using eic-shell" section.
• medium S Add examples/ with a small generator text file and a macro running BuildTree, SmearTree and TreeToHepMC.

Public headers carry Doxygen comments, a Doxyfile generates API docs, and the README and EIC web page describe the tree-building and smearing components and the namespace layout; the only hosted API docs are for version 1.0.3.

Gaps to the next level

• API docs are not published by CI; the hosted copy at www4.rcf.bnl.gov is version 1.0.3 and eic-smear classes are not found on the central EIC Doxygen site the README cites.
• Smearing algorithms and data flow are not documented with references.

Actions

• medium S Add a workflow that runs doxygen on pushes to master and tags and deploys doxygen/html to GitHub Pages, and link it from the README.

The README "Developer Notes" cover coding conventions and a one-line fork-and-PR note, and the eic organization PR and issue templates apply, but there is no description of running tests or of a development environment.

Gaps to the next level

• No CONTRIBUTING file describing development environment setup, building and running tests, and the PR process.

Actions

• medium S Move the README developer notes into CONTRIBUTING.md and add eic-shell setup, build, test commands and PR review expectations.

The 2 issues opened in 12 months were answered (median 0.69 days) and closed, but all 3 open issues are older than one year and no new issue was labeled.

Gaps to the next level

• All open issues (#6,
• No labels or other triage on new issues.

Actions

• medium S Close or label issues

Four authors committed in 24 months, but no merged PR in 12 months came from outside the maintainer group and only one institution (BNL) is documented for contributors.

Gaps to the next level

• At least 2 contributing institutions are not publicly documented.
• No external PRs merged in 12 months.

Actions

• medium S List contributors' institutions in AUTHORS and label newcomer issues to attract PRs from outside the maintainer group.

One author wrote 83% of commits in 24 months (bus factor 1), while 4 people reviewed and 3 people merged PRs in 12 months.

Gaps to the next level

• Bus factor (50%) is 1.
• No CODEOWNERS; AUTHORS names a single maintainer.

Actions

• high S Add CODEOWNERS naming two maintainers for src/, include/ and CMakeLists.txt, and have the second maintainer author changes and cut a release.

The README names two contacts and AUTHORS names a maintainer, but there is no documented decision process, maintainer path or roadmap.

Gaps to the next level

• No documented decision process or path to becoming a reviewer or maintainer.

Actions

• medium S Add GOVERNANCE.md (or a README section) naming the maintainers, how decisions are made, and how to become a maintainer.

The eic organization issue-template configuration links the ePIC Mattermost for questions and the README lists contact e-mails, but no code of conduct applies.

Gaps to the next level

• No code of conduct with a reporting contact.

Actions

• high S Add CODE_OF_CONDUCT.md with a reporting contact, or link the ePIC collaboration code of conduct from the README.

The eic-spack recipe provides the latest release 1.2.3, eic-shell ships 1.2.2, and the recipe gained 1.1.17, 1.2.1, 1.2.2 and 1.2.3 on the day of each release.

Eight tags in 24 months and a documented SemVer scheme exist, but release 1.2.1 has no notes, 1.2.2 has only a compare link, and only one tag (1.1.13) falls in the first of the two years.

Gaps to the next level

• Not every release has release notes.
• Fewer than 2 releases between October 2024 and October 2025.

Actions

• medium S Generate release notes for every tag (GitHub "Generate release notes") and backfill notes for 1.2.1 and 1.2.2.

ROOT has a minimum version, but HepMC3 and zlib are found without versions, and the source vendors gzstream (2002) and a copy of HepMC3 ReaderFactory.h for HepMC3 older than 3.2.4.

Gaps to the next level

• find_package(HepMC3) and find_package(ZLIB) have no minimum versions.
• Unmaintained vendored gzstream and HepMC3 compatibility header remain.

Actions

• medium S Add VERSION minimums to find_package(HepMC3 3.2.4 ...) and find_package(ZLIB ...) and delete include/eicsmear/HepMC_3_2_4_ReaderFactory.h.
• low M Replace vendored gzstream with ROOT or Boost.Iostreams zlib streams, or document its version and provenance in a third-party notice.

The README lists dependency versions in prose and the smearing output stores the detector configuration, but the repository documents no machine-readable environment and records no random seed or software version in outputs.

Gaps to the next level

• Running in a specific eic-shell version or other machine-readable environment is not documented.
• Random seeds (gRandom) are not recorded in smeared output.

Actions

• medium S Document in the README which eic-shell release ships each eic-smear version and how to run in it.
• medium S Write the gRandom seed and eic-smear version as TNamed objects next to the detector object in SmearTree output.

CI builds only on Linux x86_64 with the eic_xl container's GCC; macOS is mentioned in the README but not tested.

Gaps to the next level

• No second compiler, architecture or OS in CI.

Actions

• medium S Add a Clang build (CXX=clang++ in eic-shell) and a macos-latest job with Homebrew ROOT to the CI matrix.

HepMC3 is used for HepMC input and output, but generator events and smeared particles use custom ROOT classes in place of HepMC3/EDM4hep/EDM4eic records, and a verbatim copy of HepMC3 ReaderFactory.h is kept.

Gaps to the next level

• Vendored HepMC3 ReaderFactory.h duplicates HepMC3 functionality.
• Smeared output uses custom Smear::ParticleMCS classes instead of EDM4eic, without documented justification.

Actions

• medium S Remove include/eicsmear/HepMC_3_2_4_ReaderFactory.h and require HepMC3 >= 3.2.4.
• medium M Document in the README why the EicTree/Smeared formats are kept instead of HepMC3/EDM4eic, or add an EDM4eic writer for smeared output.

HepMC2/3 input and HepMC3 output are supported, but the primary outputs are ROOT TTrees of custom eic-smear classes whose schema is documented only in header comments and that need the eic-smear dictionaries to read.

Gaps to the next level

• The EicTree and Smeared tree schemas and the EIC text input format are not documented as file formats.
• Smeared output is not in an EIC-standard format (EDM4eic).

Actions

• medium M Add a document listing every branch and field of the EicTree and Smeared trees and the EIC text input format.

CI builds in the eic_xl nightly image and eic-shell ships eic-smear, but the README does not document building or running in eic-shell and CI runs no tests there.

Gaps to the next level

• The README has no eic-shell instructions.
• CI in eic-shell builds but does not test.

Actions

• medium S Add an eic-shell section to the README and run a BuildTree/SmearTree example in the existing eic-shell CI job.

The current eic-shell ships 1.2.2 and the nightly-image build succeeds with ROOT 6.40.04 and HepMC3 3.3.0 without deprecation warnings, but compatibility code for HepMC3 older than 3.2.4 remains and adaptation timing cannot be measured from public evidence.

Gaps to the next level

• Compatibility code for HepMC3 < 3.2.4 is retained; declared minimums (C++11, ROOT 6.20) lag the stack.

Actions

• medium S Raise minimums to the current eic-shell versions (ROOT 6.40, HepMC3 3.3, C++20) and remove the HepMC3 compatibility branch.

A single GPL-3.0 license is detected, compatible with ROOT (LGPL), HepMC3 (GPL-3.0) and gzstream (LGPL-2.1+); source files carry no SPDX headers and there are no contribution terms.

Gaps to the next level

• No SPDX headers; third-party code (gzstream, HepMC3 header, cpplint) is not listed in a license inventory.
• No documented contribution terms (DCO or inbound = outbound).

Actions

• low M Add SPDX-License-Identifier headers, a REUSE LICENSES/ directory covering gzstream and cpplint, and the REUSE lint to CI.

There is no CITATION.cff, Zenodo record, codemeta file or citation request in the README.

Gaps to the next level

• No machine-readable citation metadata or DOI.

Actions

• high S Add CITATION.cff listing the authors in AUTHORS and enable the Zenodo-GitHub integration for releases.

eic-smear ships in eic-shell, is a dependency of eicsmeardetectors and ejana, and is used in sPHENIX collaboration analysis code.

The maintainer and contacts are identified with BNL addresses, but no owning EIC/ePIC body, institutional commitment or funding is stated.

Gaps to the next level

• Maintenance responsibility within the EIC/ePIC structure is not documented.

Actions

• medium S State in the README the EIC/ePIC working group that owns eic-smear and any funding or institutional support.