epic-analysis

The only first-parent change in 12 months came through PR #294 with an approving review, and branch protection requires one approval; level 3 is not met because protection does not apply to administrators and was bypassed for a direct push in April 2025 and a merge with a failing required check.

Gaps to the next level

• Branch protection has enforce_admins disabled; commit 8840aca (2025-04-27) was pushed directly to main.
• PR
• No CODEOWNERS; the 12-month sample is a single PR.

Actions

• medium S Enable "Do not allow bypassing the above settings" (enforce for administrators) on the main protection rule.
• medium S Add .github/CODEOWNERS naming at least two reviewers for src/, macro/ci/, and .github/.

ci.yml runs on every PR and push to main and executes analysis and postprocessing macros on sample data, but every recorded default-branch run fails at the build jobs.

Gaps to the next level

• Fewer than 80% of default-branch runs succeed; build_all and build_no_delphes fail on main and on open PRs.

Actions

• high M Fix the build failures in build_all and build_no_delphes (merge or rework PR

There are no unit tests; CI runs analysis and postprocess macros on downloaded sample files as smoke tests, which currently do not execute because the build jobs fail.

Gaps to the next level

• No unit tests for Kinematics reconstruction methods, Weights, or Histos.
• CI produces plots but compares nothing against reference values, and its smoke tests are not running.

Actions

• medium M Add a test executable (Catch2, available in eic-shell) that checks Kinematics::CalculateDIS for each method on fixed four-vectors, run from ci.yml.

No formatter, linter, or static analyzer is configured, and the Makefile sets -Wno-deprecated without enabling -Wall.

Gaps to the next level

• No formatter or linter configuration and no compiler warning flags.

Actions

• high S Add .clang-format and .pre-commit-config.yaml with clang-format, enable pre-commit.ci, and add -Wall -Wextra to FLAGS in the Makefile.

A Makefile builds a shared library with ROOT dictionaries, but the C++ standard is unspecified, the compiler and /usr/local/lib are hard-coded, there is no install target, and analyses are driven by interpreted ROOT macros.

Gaps to the next level

• No declared C++ standard, no install or export target, and hard-coded -L/usr/local/lib (issue

Actions

• medium M Replace the Makefile with CMake that sets CMAKE_CXX_STANDARD 20, uses find_package for ROOT, podio, EDM4eic and fmt, and installs the library and headers.

The README covers eic-shell setup, Delphes installation, make targets and build options, and links ordered tutorials, but names no dependency versions and the tutorials need S3 credentials to obtain input data.

Gaps to the next level

• No dependency versions (eic-shell release, Delphes, ROOT) are named.
• No quick-start runnable without S3 credentials.

Actions

• medium S State the tested eic-shell release and Delphes tag in the README, and add a quick-start that runs tutorial/analysis_template.C on a public input file (for example via xrootd).

Public headers carry inline comments, doc/kinematics.md documents the reconstruction methods, and the README has a class flowchart, but there is no generated API reference.

Gaps to the next level

• No generated API documentation (Doxygen or similar).

Actions

• medium S Add a Doxyfile covering src/ and a GitHub Pages workflow that publishes it from main.

The README "Contributions" section says where to put macros and to open PRs, and the eic organization supplies PR and issue templates, but there is no description of build, test, or coding conventions.

Gaps to the next level

• No CONTRIBUTING covering development setup, running the CI macros locally, and coding conventions.

Actions

• medium S Add CONTRIBUTING.md covering eic-shell setup, make, running the macro/ci macros locally, code style, and the PR review process.

There were no commits in 12 months while 22 issues are open, all older than one year, and PR #297 (December 2025) has no review or comment.

Gaps to the next level

• No development activity in 12 months; open issues and PRs are not triaged and no triage process is documented.

Actions

• high S Review the 22 open issues and 10 open PRs, close stale ones, and label the rest.

Two authors committed in 24 months and none in 12 months; no institutional affiliation is measurable.

Gaps to the next level

• Fewer than 4 active authors in 24 months and no merged external PRs in 12 months.

Actions

• high M Review and merge or close the open contributor PRs (#295,

The bus factor (50%) is 1, but the one merged PR in the period was approved by a second person.

Gaps to the next level

• Bus factor below 2 and no maintainer list or CODEOWNERS.

Actions

• high S Add CODEOWNERS or a README maintainer section naming at least two maintainers.

Neither the README nor a CODEOWNERS file names maintainers, and there is no decision process, roadmap, or milestones.

Gaps to the next level

• Maintainers are not identified and no governance, milestones, or ePIC ownership is documented.

Actions

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

The eic organization issue-template configuration links the ePIC Mattermost for questions, 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 linking the ePIC collaboration code of conduct and reporting contact, and a "Getting help" README section.

A from-source Makefile build is documented, but there is no package recipe in eic-spack, Spack, or conda-forge.

Gaps to the next level

• No recipe in eic-spack or another domain package manager.

Actions

• medium M Once a CMake install exists, add an epic-analysis recipe to eic-spack for the latest release.

Eight tags exist, but the latest, v0.6.0, is from December 2022 and none were made in 24 months.

Gaps to the next level

• Fewer than 2 releases per year, no documented version scheme, and no changelog.

Actions

• medium S State SemVer in the README and tag a release with generated notes once main CI passes, then at least every six months.

deps/README.md lists the dependencies and the subrepo .gitrepo files record adage and delphes_EIC commits, but Delphes is cloned from its default branch, no versions are constrained, and mstwpdf is vendored without a source version.

Gaps to the next level

• No minimum versions for ROOT, podio, EDM4eic, fmt, or Delphes; Delphes is unpinned.
• Vendored mstwpdf has no recorded upstream version or source URL.

Actions

• medium S Pin Delphes to a release tag in deps/install_delphes.sh and declare minimum versions of ROOT, podio, EDM4eic and fmt in the build files.

The README directs users to eic-shell and CI names an eic container, but no eic-shell version is pinned and the random seed is hard-coded in source rather than recorded in outputs.

Gaps to the next level

• No pinned eic-shell release; CI uses the floating jug_xl:nightly tag.
• Seed and configuration are not written to output files.

Actions

• medium S Document the eic-shell release used for each tag and write the config file contents and seed into each output ROOT file.

CI builds only on Linux x86_64 with GCC (the Makefile hard-codes g++), and the data-access and HPC tooling assume the BNL S3 endpoint and JLab Slurm.

Gaps to the next level

• Single compiler and OS tested; S3 host and JLab xrootd prefix hard-coded in scripts.

Actions

• medium S Use CXX ?= g++ in the Makefile and add a Clang build job to ci.yml; make the S3 host and xrootd prefix configurable.

The project uses ROOT, fmt, and (optionally) podio, EDM4hep and EDM4eic, but reads ePIC files through hard-coded TTree branch names and recomputes DIS kinematics that EICrecon already provides as InclusiveKinematics* collections.

Gaps to the next level

• Raw TTreeReader access to EDM4eic branches instead of the podio API; no documented reason for recomputing EICrecon kinematics.
• Vendors mstwpdf while LHAPDF ships in eic-shell.

Actions

• medium M Port AnalysisEpic to podio::ROOTReader frames with EDM4eic collections (issue

Inputs include EDM4eic podio files, but outputs are ROOT files of TObjArray histograms, streamed project classes (Histos, BinSet), and flat trees whose schema is not documented.

Gaps to the next level

• Output schema (SidisTree, HFSTree, ParticleTree branches) is not documented, and Histos objects need the project dictionary to read.

Actions

• medium S Add doc/output.md listing every branch of SidisTree, HFSTree and ParticleTree with units.

The README documents building in eic-shell, but every recorded CI build in the eic image fails, and the C++20 compatibility fix (PR #295) and /usr/local path fix (issue #292) remain unmerged.

Gaps to the next level

• No public evidence of a successful build in a current eic-shell image.
• CI targets the legacy jug_xl:nightly image name rather than eic_xl.

Actions

• high M Switch ci.yml to platform-release eic_xl:nightly and fix the build so build_all and build_no_delphes pass.

Known incompatibilities with the current stack have been open for more than 6 months: issue #292 (May 2024), PR #295 for C++20 builds (January 2025), and the optional podio reader uses podio::EventStore, which podio removed before 1.0.

Gaps to the next level

• Does not build against the current eic-shell stack (ROOT C++20, podio 1.8).

Actions

• high M Merge the C++20 fixes from PR

LGPL-3.0 is detected and source files carry SPDX headers, but the default build links GPL-3.0 Delphes into the LGPL library and the vendored mstwpdf carries no license statement.

Gaps to the next level

• The default build links a GPL-3.0 dependency into an LGPL-3.0 library.
• No license recorded for deps/mstwpdf.

Actions

• medium S Document in the README that builds with Delphes are distributed under GPL-3.0 (or default to EXCLUDE_DELPHES), and record the mstwpdf license in deps/README.md.

There is no citation file, DOI, or citation request.

Gaps to the next level

• No citation information.

Actions

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

Public use is limited to a SIDIS asymmetry project that consumes its SidisTree format; no EIC repository, benchmark, or campaign depends on it.

Gaps to the next level

• No use as a dependency of another EIC repository or in benchmarks or campaigns.

Actions

• medium M Contribute a SIDIS kinematics benchmark that uses the project to physics_benchmarks, and list known users in the README.

No maintainer affiliations, owning working group, or funding acknowledgement are stated, and there were no commits in 12 months.

Gaps to the next level

• No identifiable maintainer affiliations or institutional commitment.

Actions

• high S State the maintainers, their institutions, and the owning ePIC working group in the README.