# Sustainability action plan: HEPMC_Merger

From the EIC Software Sustainability Review, pass `2026-10-12`, assessed at commit `a86fdd66ffd5`. Full assessment: https://eic.github.io/SoftwareSustainabilityReview/projects/hepmc-merger.html

Levels: 0 Absent · 1 Initial · 2 Established · 3 Sustained. Each item names the step to the next level.

## High priority

- [ ] Add `.clang-format` and `.pre-commit-config.yaml` with clang-format and enable pre-commit.ci. *(`eng.static-quality`, now level 0, effort S)*
- [ ] Add `target_compile_options(SignalBackgroundMerger PRIVATE -Wall -Wextra)` in `CMakeLists.txt`. *(`eng.static-quality`, now level 0, effort S)*
- [ ] Add `.github/CODEOWNERS` naming at least two current maintainers and list them in the README. *(`com.bus-factor`, now level 1, effort S)*
- [ ] Link the ePIC collaboration code of conduct with its reporting contact from the README (or add `CODE_OF_CONDUCT.md` in `eic/.github`). *(`com.conduct`, now level 1, effort S)*
- [ ] Add a `LICENSE` file (LGPL-3.0-or-later, as suggested in issue *(`via.license`, now level 0, effort S)*
- [ ] Add `CITATION.cff` listing the authors named in the banner and enable the Zenodo–GitHub integration. *(`via.citation`, now level 0, effort S)*

## Medium priority

- [ ] Register tests with `enable_testing()`/`add_test` in `CMakeLists.txt` and run `ctest --test-dir build` in the `build` job. *(`eng.ci`, now level 1, effort 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. *(`eng.testing`, now level 1, effort S)*
- [ ] Remove the default `--signalFile` URL (require the option) and move or delete the legacy scripts in `python/`. *(`eng.modularity`, now level 1, effort 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. *(`doc.user`, now level 1, effort 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. *(`doc.developer`, now level 1, effort S)*
- [ ] Add `CONTRIBUTING.md` covering building in eic-shell, running the smoke test, code style and the PR review rule. *(`doc.contributing`, now level 1, effort S)*
- [ ] Close issues resolved by later PRs (#5 by the C++ rewrite with ROOT I/O, *(`com.responsiveness`, now level 1, effort S)*
- [ ] List the contributing institutions in the README and label newcomer issues to attract a contributor from a second institution. *(`com.contributors`, now level 1, effort S)*
- [ ] Add a README section stating the owning ePIC group, how decisions are made, and the planned status relative to TimeframeBuilder. *(`com.governance`, now level 1, effort S)*
- [ ] State SemVer in the README and add breaking-change and migration notes to release notes (starting from v2.0.0's CLI change). *(`dist.releases`, now level 1, effort S)*
- [ ] Replace `argparse/argparse.hpp` with `find_package(CLI11)` (shipped in eic-shell) or record the vendored argparse version. *(`dist.dependencies`, now level 1, effort S)*
- [ ] Add `hepmc_merger_rng_seed`, `hepmc_merger_squash_time` and status-shift attributes to the GenRunInfo in `merge()`. *(`dist.reproducibility`, now level 1, effort S)*
- [ ] Document in the README the eic-shell release that ships each merger release. *(`dist.reproducibility`, now level 1, effort S)*
- [ ] Add a Clang build (`CXX=clang++` in eic-shell) or a `macos-latest` job to `.github/workflows/linux-eic-shell.yml`. *(`dist.portability`, now level 1, effort S)*
- [ ] Add a CI step that reads the merged output with uproot or pyhepmc and checks event count and `hepmc_merger_*` attributes. *(`eic.data-model`, now level 2, effort S)*
- [ ] Add a README section on running `SignalBackgroundMerger` from eic-shell and building it there. *(`eic.environment`, now level 1, effort S)*
- [ ] State in the README the owning ePIC working group and the maintenance plan until TimeframeBuilder replaces the merger. *(`via.support`, now level 1, effort S)*
- [ ] Add Catch2 tests under `tests/` for `poissonTimes`, `parse_backgrounds` and skip wrapping using the small `.hepmc` files in `python/`, registered with `add_test`. *(`eng.testing`, now level 1, effort M)*
- [ ] Split `SignalBackgroundMerger.cpp` into a library (`include/`, `src/`) for slice building and readers, plus a thin `main`. *(`eng.modularity`, now level 1, effort M)*

## Low priority

- [ ] Set `fetch-depth: 0` on `actions/checkout` in `.github/workflows/linux-eic-shell.yml` so the built version matches the tag. *(`eng.ci`, now level 1, effort S)*
- [ ] Remove `python/requirements.txt` with the legacy scripts, or add minimum versions. *(`dist.dependencies`, now level 1, effort S)*
- [ ] Raise `cmake_minimum_required` to 3.16 and the HepMC3 and ROOT minimums to the versions in current eic-shell. *(`eic.currency`, now level 2, effort S)*