TimeframeBuilder

All first-parent commits in 12 months came from PRs under an active ruleset that requires a PR, but the ruleset requires zero approvals and only 5.7% of merged PRs had a review from someone other than the author; most PRs are self-merged within hours.

Gaps to the next level

• Fewer than 50% of merged PRs are reviewed by someone other than the author.
• The ruleset sets required_approving_review_count to 0; no CODEOWNERS exists.

Actions

• high S Set the main ruleset to require one approving review and have a second person review every PR.

linux-eic-shell.yml builds in eic-shell on every PR and push to main (87.5% default-branch success) and runs merges, npsim and EICrecon end to end, but there is no test suite: the jobs only check that output files exist and the capybara comparison produces a report without failing on differences.

Gaps to the next level

• CI runs no test suite; end-to-end jobs pass whenever output files are written.
• Passing CI is not a required status check in the ruleset.

Actions

• medium S Add a ctest step to the build job in linux-eic-shell.yml once unit tests exist (see eng.testing).
• medium M Make the capybara job fail when the HepMC3-first and EDM4hep-first EICrecon outputs differ beyond a tolerance.

There are no test files or test framework; the only automated checks are CI smoke runs on sample data and a capybara comparison report, and the README's test_standalone binary does not exist in the build.

Gaps to the next level

• No unit tests for the time-offset, bunch-crossing, reference-remapping or config-parsing code.

Actions

• high M Add Catch2 unit tests for DataSource::UpdateTimeOffset, CommandLineParser and EDM4hep reference remapping, registered with ctest.

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

Gaps to the next level

• No formatter or linter is configured or enforced, and compiler warnings are not enabled.

Actions

• high S Add .clang-format and .pre-commit-config.yaml with clang-format, enable pre-commit.ci, and add -Wall -Wextra to CMakeLists.txt.

CMake with C++20 builds one executable from abstract DataSource/DataHandler interfaces with EDM4hep and HepMC3 backends, configuration lives in YAML and CLI options, and the largest file has 506 lines; the code is not installable as a reusable library and CMakeLists.txt hard-codes link_directories(/opt/local/lib).

Gaps to the next level

• Only the executable is installed; no library or exported CMake package config allows reuse of the data sources and handlers.

Actions

• medium M Build the sources into a timeframebuilder library with installed headers and install(EXPORT ...) package config, and remove link_directories(/opt/local/lib).

The README documents build steps, all CLI and YAML options and usage patterns, but it lists dependencies without versions (except CMake 3.16), tells users to run ./build.sh while the script is make.sh, does not mention eic-shell, and no example ships with input data.

Gaps to the next level

• Dependency versions and the eic-shell route are missing, and the build instruction names a non-existent build.sh.
• No runnable quick-start example with obtainable input files.

Actions

• medium S Add an "Installation" section covering the preinstalled timeframe_builder in eic-shell and from-source builds with minimum podio, EDM4hep, HepMC3, ROOT and yaml-cpp versions; fix build.sh to make.sh.
• medium S Add a quick-start that runs configs/config_ci.yml on the XRootD sample files used in CI.

The abstract interfaces in DataSource.h and DataHandler.h carry Doxygen-style comments and the README has an architecture section, but there is no generated API reference and the architecture section names a MergedCollections structure and file roles that no longer match the code.

Gaps to the next level

• No generated API documentation; the architecture overview is out of date.

Actions

• medium S Add a Doxyfile and a job that publishes the API docs next to the existing GitHub Pages reports, and update the README architecture section to the DataSource/DataHandler design.

The README's "Development and Contributing" section lists the code structure and a test command for a binary that does not exist; there is no CONTRIBUTING file, and only the eic organization PR template applies.

Gaps to the next level

• No CONTRIBUTING describing eic-shell setup, build, tests, coding conventions and the PR process.

Actions

• high S Add CONTRIBUTING.md covering eic-shell setup, make.sh, running the CI chain locally, coding conventions and PR review.

6 of the 10 issues opened in 12 months received no response and none were labeled; most open issues are the maintainer's own to-do items.

Gaps to the next level

• The majority of issues opened in 12 months received no response; no labels are used.

Actions

• high S Respond to and label every open issue, closing or scheduling the five older than one year.

Two people authored commits in 24 months, all from one e-mail domain, and no PR from outside the maintainer group was merged in 12 months.

Gaps to the next level

• Fewer than 4 active authors and a single institution.

Actions

• high M Recruit a co-developer from another ePIC institution through the ePIC simulation/background working group and merge their PRs.

The top author wrote 97.7% of commits in 24 months and made the only release, while two people reviewed and three merged PRs in 12 months; no CODEOWNERS or maintainer list exists.

Gaps to the next level

• Bus factor 1 and no CODEOWNERS or maintainer list naming at least two people.

Actions

• high S Add CODEOWNERS naming two maintainers and have the second maintainer author and review changes to src/.

Decisions are discussed in some public issues (#88), but the README only says to "contact the development team" and no CODEOWNERS or governance file names maintainers, a decision process, or an owning ePIC group.

Gaps to the next level

• Maintainers are not identified in the README or a CODEOWNERS file.

Actions

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

The README directs questions to the issue tracker, but no code of conduct exists in the repository or the eic organization.

Gaps to the next level

• No code of conduct with a reporting contact applies.

Actions

• high S Add CODE_OF_CONDUCT.md linking the ePIC collaboration code of conduct and its reporting contact.

The eic-spack recipe provides v0.9.0, v0.9.1 and v0.9.2, and eic/containers ships v0.9.2 in eic-shell; the v0.9.2 recipe and container updates landed 0 and 5 days after the release.

Three tags (v0.9.0, v0.9.1, v0.9.2) exist, but only v0.9.2 has a GitHub release with notes, no version scheme is documented, and there is no changelog.

Gaps to the next level

• No documented version scheme; v0.9.0 and v0.9.1 have no release notes.

Actions

• medium S State SemVer in the README and publish a GitHub release with generated notes for every tag.

ROOT, podio, EDM4hep, yaml-cpp, HepMC3 and Arrow are found with find_package without version constraints, there is no Dependabot or Renovate configuration, and actions are referenced by tag or @main.

Gaps to the next level

• No minimum versions declared for any dependency.

Actions

• medium S Add minimum VERSION arguments to every find_package in CMakeLists.txt matching the current eic-shell versions.

The README lists prerequisites in prose, and the seed and configuration are written into HepMC3 output, but no environment specification or eic-shell version is documented, the default seed is drawn from random_device, and EDM4hep output does not record the seed or configuration.

Gaps to the next level

• No documented machine-readable environment, and EDM4hep outputs carry no seed or configuration.

Actions

• medium S Document running in a named eic-shell release in the README and write the seed and configuration into the EDM4hep output's podio metadata.

CI builds only with the eic-shell compiler on ubuntu-24.04 x86_64; no second compiler, architecture or OS is tested.

Gaps to the next level

• Builds are tested with a single OS and compiler.

Actions

• medium S Add a job to linux-eic-shell.yml that builds with CXX=clang++ in eic-shell.

The code uses EDM4hep types, podio ObjectIDs and HepMC3 I/O, but EDM4hep files are read and written through raw ROOT branches instead of podio readers/writers (issue #57 asks for a podio backend), and the HepMC3 backend duplicates the shipped HEPMC_Merger without a documented justification.

Gaps to the next level

• EDM4hep I/O reimplements podio's ROOT layout instead of using podio readers and writers.
• The overlap with HEPMC_Merger (SignalBackgroundMerger) is not justified in the documentation.

Actions

• medium M Implement the EDM4hep backend with podio::ROOTReader/ROOTWriter frames (issue
• medium S Document in the README how the HepMC3 mode relates to HEPMC_Merger and when each should be used.

Inputs and outputs are EDM4hep podio-layout ROOT files and HepMC3 ROOT trees, and CI runs EICrecon and npsim on the outputs; no data-model version is declared or checked and no round-trip test exists.

Gaps to the next level

• The EDM4hep version is neither recorded nor checked on read, and there is no I/O round-trip test.

Actions

• medium M Check the input podio_metadata EDM4hep version against the linked EDM4hep and add a round-trip test reading merged output with uproot.

Every CI job builds and runs in eic_xl:nightly through eic/run-cvmfs-osg-eic-shell, but the README does not mention eic-shell for building or running.

Gaps to the next level

• Building and running in eic-shell is not documented.

Actions

• medium S Add an eic-shell section to the README covering the preinstalled timeframe_builder and building from source inside eic-shell.

v0.9.2 is built and shipped in the current eic-shell (podio 1.8, EDM4hep 1.1, HepMC3 3.3.0) and CI passes against the nightly image; the raw-branch I/O depends on podio's internal ROOT layout, and there is no record of adapting to new component releases.

Gaps to the next level

• No evidence of adapting to component releases within one eic-shell cycle; I/O relies on podio internal branch naming.

Actions

• medium M Replace hard-coded podio branch names (_MCParticles_daughters, GPIntValues) with podio API calls so podio layout changes do not break merging.

No LICENSE file exists and GitHub detects no license, although the README refers to "the LICENSE file found in the top-level directory".

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 and declare it in the eic-spack recipe.

No CITATION.cff, Zenodo DOI, codemeta or citation request exists.

Gaps to the next level

• No citation information.

Actions

• high S Add CITATION.cff with the authors and enable the Zenodo-GitHub integration.

TimeframeBuilder ships in eic-shell through the eic/containers spack environment; a code search found no use in EIC benchmarks, campaigns or other repositories beyond packaging.

The main author's affiliation is identifiable from commit e-mail domains and a public profile, but no institutional commitment, funding or owning ePIC body is stated.

Gaps to the next level

• Maintenance responsibility is not assigned within the EIC or ePIC structure in the documentation.

Actions

• medium S State the owning ePIC working group and maintainer institutions in the README.