afterburner

All 12 first-parent commits in 12 months came from PRs (the 4 non-merge commits are squash merges of PRs #15, #21, #23 and #26, so the 0.667 metric undercounts), every merged PR was reviewed, branch protection requires one approving review, and the eic organization PR template applies.

The single workflow builds in eic-shell and runs one end-to-end smoke run on PRs to main, but it has no push trigger, so the default branch is never built, and it runs no test suite.

Gaps to the next level

• The workflow does not run on pushes to main; default-branch success rate cannot be measured.
• CI checks only that output files exist; no test suite (ctest/pytest) runs.
• Branch protection has no required status checks.

Actions

• medium S Add push: branches: [main] to the on: block of .github/workflows/linux-eic-shell.yml.
• medium S Run pytest python/test_abconv.py with TEST_ABCONV_EXE=install/bin/abconv (and ctest once tests are registered) in the "Run test" step.

The only test file checks that abconv --help prints usage and is not run in CI; CI runs one end-to-end conversion and checks only that output files exist, with no unit tests of the afterburner algorithms.

Gaps to the next level

• No unit tests for Afterburner, Smearer or EicConfigurator presets.
• enable_testing() is called but no tests are registered with CTest.
• The Pythia8 comparison in python/comparison.ipynb is manual and not automated.

Actions

• medium M Add Catch2 unit tests under cpp/tests/ for Smearer and Afterburner::process_event (crossing angle and vertex widths per preset) registered with add_test.
• medium M Assert in CI that output vertex and angle distributions of the generated sample match expected crossing angle and widths within tolerance.

No formatter, linter, static analyzer or compiler warning flags are configured in the repository or CI.

Gaps to the next level

• No .clang-format, .clang-tidy or pre-commit configuration.
• No -Wall -Wextra or equivalent warning flags in the CMake files.

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(... PRIVATE -Wall -Wextra -Wpedantic) to the three targets in cpp/*/CMakeLists.txt.

CMake builds a static afterburner library, a benchmark library and the abconv tool with C++20, but all beam presets are compiled into a 2172-line EicConfigurator.cc and only the abconv executable is installed (no library, headers or package config).

Gaps to the next level

• Beam parameters are hard-coded in C++; beam_configs/default.yaml is placeholder content and YAML loading is not implemented.
• The afterburner library and headers are not installed, although the README advertises a C++ API.
• cpp/afterburner/CMakeLists.txt references a non-existent ../external/json_struct/ directory.

Actions

• medium M Move the beam presets from EicConfigurator.cc into YAML files under beam_configs/ loaded at run time (issue
• medium S Install the afterburner library and its headers with install(TARGETS ... EXPORT) and install(DIRECTORY ...).

The README has build steps, CLI examples and an options table, but lists only yaml-cpp as a dependency although CMake requires HepMC3, CLHEP, GSL and ROOT, gives no versions, and has no runnable example input.

Gaps to the next level

• HepMC3, CLHEP, GSL and ROOT and all minimum versions are missing from the install instructions.
• Examples use a user-supplied my.hepmc; python/gen_hepmc_event.py is not documented as a quick-start input.
• README links to beam parameters point to the old eicweb.phy.anl.gov repository.

Actions

• medium S List every find_package dependency with minimum versions in the README "Installation" section and state that eic-shell provides them.
• medium S Add a README quick start that generates input with python/gen_hepmc_event.py and runs abconv on it.

Some header members have Doxygen-style comments and the README describes the algorithm steps, but there is no generated API reference and no architecture overview of the library, converter and benchmark components.

Gaps to the next level

• No Doxygen or other generated API documentation.
• No architecture overview of afterburner, abconv and benchmark.

Actions

• medium S Add a Doxyfile and a GitHub Pages workflow publishing the API docs for cpp/afterburner/*.hh.
• medium S Add docs/architecture.md describing the library, converter and histogrammer and their data flow.

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

Gaps to the next level

• No CONTRIBUTING.md covering eic-shell setup, build, tests and PR conventions.

Actions

• medium S Add CONTRIBUTING.md describing development in eic-shell, the CMake build, running the CI smoke test locally, and PR conventions.

Four of the five issues opened in 12 months have no response, no new issue is labeled, and 8 of 12 open issues are older than one year.

Gaps to the next level

• Most issues opened in 12 months received no response.
• External PRs

Actions

• high S Respond to and label issues
• medium S Close or label the eight issues older than one year (#1,

Six authors from two email domains committed in 24 months, but no PR from outside the maintainer group was merged in 12 months, and the two open external PRs are unreviewed.

Gaps to the next level

• No external PRs merged in the last 12 months.

Actions

• medium S Review and merge or close external PRs

The top author wrote 52% of commits in 24 months, while three people review and four merge; no CODEOWNERS or maintainer list exists in the repository.

Gaps to the next level

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

Actions

• high S Add .github/CODEOWNERS naming at least two owners for cpp/.

Design decisions are discussed in public issues (#11, #12), but neither the README nor a CODEOWNERS file identifies the maintainers, and there is no documented decision process, roadmap or milestone.

Gaps to the next level

• Maintainers are not named in the repository.
• No documented decision process or path to maintainership.

Actions

• high S Add a "Maintainers" section to the README naming the maintainers, their roles and the owning ePIC working group.

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

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 0.2.1, eic-shell ships 0.2.1, and the recipe was updated within one day of the v0.2.0 and v0.2.1 releases.

Three releases with generated notes appeared in 24 months, but only one between October 2024 and October 2025, no version scheme is documented, and abconv --version reports 0.1.3 while CMake declares 1.0.0 at tag v0.2.1.

Gaps to the next level

• Fewer than 2 releases in the first 12 months of the 24-month window.
• No documented version scheme; the version strings disagree with the tags.

Actions

• medium S State SemVer in the README and derive the --version string from project(VERSION ...) set to the release tag.
• medium S Tag a release at least every six months with generated release notes.

Dependencies are declared with find_package but without versions, CLI11 2.0.0 and HepMC3's example ReaderGZ/gzstream are vendored, and there is no update monitoring or SHA pinning.

Gaps to the next level

• No minimum versions on any find_package call.
• Vendored CLI11 2.0.0 while eic-shell ships CLI11 2.4.2; vendored ReaderGZ.h and gzstream.
• cpp/afterburner/CMakeLists.txt lists a non-existent external/json_struct include path.

Actions

• medium S Add VERSION arguments to the find_package calls for HepMC3, yaml-cpp, CLHEP, GSL and ROOT.
• medium S Replace cpp/external/CLI with find_package(CLI11) and drop the json_struct include path.

The README points to eic-shell, where a pinned version is preinstalled, and abconv writes the beam configuration into HepMC3 run attributes, but no eic-shell version is documented, and the random seed is fixed at 1 in code, cannot be configured, and is not recorded.

Gaps to the next level

• No documented eic-shell version or other machine-readable environment in the repository.
• The random seed is hard-coded (_smear(1)); AfterburnerConfig::random_seed is unused and not written to output.

Actions

• medium S Add a --seed option wired to AfterburnerConfig::random_seed and write the seed and abconv version into the GenRunInfo attributes.
• medium S Document in the README the eic-shell release that ships each afterburner release.

CI builds only on Linux x86_64 with the eic-shell GCC toolchain; no other compiler, architecture or OS is tested, although no site-specific paths appear in the code.

Gaps to the next level

• No second compiler, architecture or OS in CI.

Actions

• medium S Add a CI matrix job building with Clang (CXX=clang++ in eic-shell) or on macos-latest with Homebrew dependencies.

Event I/O uses HepMC3 readers and writers, but cpp/abconv/ReaderGZ.h and gzstream are an old copy of HepMC3 code for compressed input that HepMC3 has provided in its library (ReaderGZ, deduce_reader) since 3.2.5.

Gaps to the next level

• Local copy of HepMC3 gzip reader instead of the HepMC3 library's compressed I/O.

Actions

• medium S Remove ReaderGZ.h, gzstream.* and the gz format path, and rely on HepMC3::deduce_reader with HepMC3 built with compression.

Inputs and outputs are HepMC3 (ASCII or ROOT tree), the EIC generator standard, with beam configuration stored as run-info attributes; no format version is declared or checked and no round-trip test exists.

Gaps to the next level

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

Actions

• medium S Add an attribute recording the afterburner version and attribute schema version, and a CI test that reads the output back with pyHepMC3 or uproot and checks the attributes.

The README directs users to the preinstalled version in eic-shell, and CI builds and runs abconv in eic_xl:nightly through eic/run-cvmfs-osg-eic-shell; no pinned stable eic-shell release is tested.

Gaps to the next level

• CI tests only the nightly image, not a pinned stable eic-shell release.
• The README does not state that the from-source build is done inside eic-shell.

Actions

• medium S Add a matrix over platform-release with a pinned eic_xl:<release> and eic_xl:nightly in .github/workflows/linux-eic-shell.yml.

The current release is built and shipped in eic-shell against HepMC3 3.3.0 and ROOT 6.40, and CI passes on the nightly image; the vendored HepMC3 compressed reader and CLI11 2.0.0 lag the versions in the stack.

Gaps to the next level

• Vendored copies of HepMC3 reader code and CLI11 2.0.0 are not kept current with the stack.

Actions

• medium S Drop the vendored ReaderGZ.h and CLI11 copies in favour of the HepMC3 and CLI11 versions shipped in eic-shell.

The repository has no LICENSE file and GitHub detects no license; issue #1 requesting one has been open since 2022, while the repository contains BSD-3-Clause (CLI11) and LGPL-2.1 (gzstream) third-party code.

Gaps to the next level

• No license; the code is all rights reserved.

Actions

• high S Add a LICENSE file with an OSI-approved license compatible with the bundled LGPL-2.1 gzstream code, agreed by the copyright holders.

There is no CITATION.cff, Zenodo DOI, codemeta or author list; the README references a beam effects note but does not ask users to cite the software.

Gaps to the next level

• No citation information or contributor list.

Actions

• high S Add CITATION.cff listing the contributors and enable the Zenodo-GitHub integration.

afterburner ships in eic-shell and its output is used in ePIC simulation campaign datasets and productions, and it is taught in the EIC analysis tutorial.

Maintainers are identifiable through the eic-spack recipe and commit email domains, but the repository states no owning ePIC working group, institutional commitment or funding.

Gaps to the next level

• No maintenance responsibility assigned within the EIC/ePIC structure is documented.

Actions

• medium S State in the README the ePIC working group that owns afterburner and the maintainers' institutions.