HEPMC_Merger

All first-parent commits on main in 12 months came from PRs and every merged PR was reviewed by someone other than the author; an active ruleset requires one approving review, resolved threads and the build/smoke-test checks, and the eic organization PR template applies.

linux-eic-shell.yml builds in eic-shell on every PR and push to main (3 of 3 default-branch runs succeeded) and is a required check, but it runs no test suite; the only check is one smoke run whose result is verified by ls -la on the output file.

Gaps to the next level

• No test suite (ctest) runs in CI; the smoke run checks only that the output file exists.
• The actions/checkout step fetches no tags, so CI builds report version 0.0.0-unknown (CMake warning in run 37384280511).

Actions

• medium S Register tests with enable_testing()/add_test in CMakeLists.txt and run ctest --test-dir build in the build job.
• low S Set fetch-depth: 0 on actions/checkout in .github/workflows/linux-eic-shell.yml so the built version matches the tag.

There are no test files or test framework; the only automated test is a CI smoke run of one campaign configuration that checks the output file exists.

Gaps to the next level

• No unit tests for Poisson time placement, weighted sampling, background cycling or status shifting.
• No check of output content (event counts, vertex times, run attributes).

Actions

• medium M Add Catch2 tests under tests/ for poissonTimes, parse_backgrounds and skip wrapping using the small .hepmc files in python/, registered with add_test.
• medium S Add a CI step that runs the merger on local test files with a fixed --rngSeed and asserts placed event counts and GenRunInfo attributes with pyhepmc or uproot.

No formatter, linter, pre-commit or static-analysis configuration exists, and CMakeLists.txt sets no warning flags.

Gaps to the next level

• No formatter or linter configured or enforced.
• No compiler warning flags.

Actions

• high S Add .clang-format and .pre-commit-config.yaml with clang-format and enable pre-commit.ci.
• high S Add target_compile_options(SignalBackgroundMerger PRIVATE -Wall -Wextra) in CMakeLists.txt.

CMake builds and installs one C++17 executable, but all logic (CLI parsing, I/O, sampling, metadata) sits in one 824-line class, and the default signal input is a server URL compiled into the source that had to be edited in PR #31 when the endpoint moved.

Gaps to the next level

• Single-file monolithic class with public data members; no separation into components.
• Default input file URL hard-coded in source.
• Three legacy Python merger scripts and a notebook remain alongside the C++ code.

Actions

• medium M Split SignalBackgroundMerger.cpp into a library (include/, src/) for slice building and readers, plus a thin main.
• medium S Remove the default --signalFile URL (require the option) and move or delete the legacy scripts in python/.

The README gives build steps and a --help pointer, but lists ROOT and HepMC without versions, does not mention eic-shell, and its usage example uses --bg1File/--bg1Freq options that the current CLI (since v2.0.0) rejects.

Gaps to the next level

• README usage example and default-behaviour text are outdated and not runnable.
• Dependency versions and the eic-shell route are not documented.
• The --bgFile tuple and status-shift options are documented only in --help.

Actions

• medium S Replace the README example with the --bgFile <file> <freq> [skip] [status] form from the CI smoke test and add an "Installation" section covering eic-shell and HepMC3 >= 3.2.6, ROOT >= 6.20.

A few methods carry comments and the README "Logic" section describes the sampling in one paragraph, but there is no generated API reference and no architecture overview.

Gaps to the next level

• No generated API documentation.
• No description of slice building, weighted sampling and the GenRunInfo attribute schema.

Actions

• medium S Add docs/design.md describing the slice loop, weighted sampling, status shifting and the hepmc_merger_* run attributes, plus Doxygen comments on each method.

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

Gaps to the next level

• No CONTRIBUTING describing eic-shell setup, build, test and PR conventions.

Actions

• medium S Add CONTRIBUTING.md covering building in eic-shell, running the smoke test, code style and the PR review rule.

All 3 issues opened in 12 months got a same-day response, but 9 of 10 open issues are older than one year and no new issue is labeled.

Gaps to the next level

• More than half of open issues are older than one year (#1,
• No issue labeling or triage.

Actions

• medium S Close issues resolved by later PRs (#5 by the C++ rewrite with ROOT I/O,

Five authors committed in 24 months, but all commits map to one institutional e-mail domain, no new authors joined in 12 months, and no merged PR came from outside the maintainer group.

Gaps to the next level

• Contributions come from a single institutional domain per the metrics.
• No merged external PRs in 12 months.

Actions

• medium S List the contributing institutions in the README and label newcomer issues to attract a contributor from a second institution.

The top author wrote 50% of commits in 24 months (bus factor 1), while three people review and merge and two people cut releases; no CODEOWNERS exists and the README names one current maintainer.

Gaps to the next level

• Bus factor (50%) is 1.
• No CODEOWNERS or maintainer list naming at least two current maintainers.

Actions

• high S Add .github/CODEOWNERS naming at least two current maintainers and list them in the README.

The README names the C++ maintainer and decisions are discussed in public issues, but there is no documented decision process or maintainer path, and the stated plan to retire the merger in favour of TimeframeBuilder is recorded only in an issue comment.

Gaps to the next level

• No documented decision process, maintainer path, roadmap or milestones.
• Deprecation plan relative to TimeframeBuilder not documented.

Actions

• medium S Add a README section stating the owning ePIC group, how decisions are made, and the planned status relative to TimeframeBuilder.

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

Gaps to the next level

• No code of conduct with a reporting contact.

Actions

• high S Link the ePIC collaboration code of conduct with its reporting contact from the README (or add CODE_OF_CONDUCT.md in eic/.github).

The eic-spack hepmcmerger recipe provides the latest release 2.4.0, which eic-shell ships, and the recipe gained v2.2.0, v2.3.0 and v2.4.0 on their release days.

Eight releases with generated notes appeared in 24 months, but no version scheme is documented and v2.0.0, which replaced the --bgNFile options, carries no migration note.

Gaps to the next level

• No documented version scheme.
• No changelog flagging breaking changes.

Actions

• medium S State SemVer in the README and add breaking-change and migration notes to release notes (starting from v2.0.0's CLI change).

HepMC3 (>= 3.2.6) and ROOT (>= 6.20) have minimum versions, but argparse is vendored without a version and unchanged since 2024 (eic-shell ships CLI11), python/requirements.txt has no versions, and there is no update monitoring.

Gaps to the next level

• Vendored argparse without recorded version.
• Python requirements unversioned.

Actions

• medium S Replace argparse/argparse.hpp with find_package(CLI11) (shipped in eic-shell) or record the vendored argparse version.
• low S Remove python/requirements.txt with the legacy scripts, or add minimum versions.

Outputs record the merger version, input files, frequencies, skips and window in GenRunInfo, but the random seed and status shifts are not recorded, and no environment (eic-shell version) is documented in the repository.

Gaps to the next level

• --rngSeed, --squashTime and status shifts are not written to the output metadata.
• No documented eic-shell version or container for running.

Actions

• medium S Add hepmc_merger_rng_seed, hepmc_merger_squash_time and status-shift attributes to the GenRunInfo in merge().
• medium S Document in the README the eic-shell release that ships each merger release.

CI builds only on Linux with the eic-shell GCC toolchain; the source contains a macOS code path that is not built in CI.

Gaps to the next level

• Single OS and compiler tested.

Actions

• medium S Add a Clang build (CXX=clang++ in eic-shell) or a macos-latest job to .github/workflows/linux-eic-shell.yml.

All event I/O uses HepMC3 readers and writers with no parallel implementation, and the merger is an EIC-supported component run by the ePIC production payload and by the TimeframeBuilder CI.

Inputs and outputs are HepMC3 (ASCII or ROOT tree) with configuration stored as hepmc_merger_* run attributes; no attribute-schema version is declared or checked and no round-trip test exists.

Gaps to the next level

• No declared version of the run-attribute schema.
• No I/O round-trip test.

Actions

• medium S Add a CI step that reads the merged output with uproot or pyhepmc and checks event count and hepmc_merger_* attributes.

CI builds and runs the merger in eic_xl:nightly through eic/run-cvmfs-osg-eic-shell, but the README does not document building or running in eic-shell (only a commented-out ATHENA container line).

Gaps to the next level

• eic-shell use is not documented.
• No pinned stable eic-shell release is tested.

Actions

• medium S Add a README section on running SignalBackgroundMerger from eic-shell and building it there.

eic-shell ships the latest release 2.4.0 and the nightly eic-shell build passes, with HepMC3 and ROOT minimums below the shipped 3.3.0 and 6.40.04; there is no record of adaptation timing to component releases and the build emits a CMake deprecation warning for cmake_minimum_required(VERSION 3.8).

Gaps to the next level

• No evidence of adapting to new component releases within one eic-shell cycle.
• CMake deprecation warning in CI.

Actions

• low S Raise cmake_minimum_required to 3.16 and the HepMC3 and ROOT minimums to the versions in current eic-shell.

The repository has no LICENSE file and no license is detected; issue #10 requesting a free software license has been open since June 2024.

Gaps to the next level

• No license.

Actions

• high S Add a LICENSE file (LGPL-3.0-or-later, as suggested in issue

There is no CITATION.cff, Zenodo DOI, codemeta or author file, and the README does not ask users to cite the software.

Gaps to the next level

• No citation information.

Actions

• high S Add CITATION.cff listing the authors named in the banner and enable the Zenodo–GitHub integration.

The merger ships in eic-shell, is the default background merger of the ePIC production payload (swf-epicprod), and is used by a JLab simulation pipeline to mix signal and background.

The README and banner name maintainers with institutional affiliations, but no owning ePIC body, institutional commitment or funding is stated, and the maintainer intends to retire the tool (issue #29).

Gaps to the next level

• No maintenance responsibility assigned within EIC/ePIC structures and no funding acknowledgement.

Actions

• medium S State in the README the owning ePIC working group and the maintenance plan until TimeframeBuilder replaces the merger.