EDM4eic

All first-parent commits in 12 months came through PRs and 95.8% of merged PRs were reviewed by a non-author; branch protection on main requires one approving and code-owner review (enforced for admins), and a PR template sets expectations.

linux-eic-shell.yml builds and installs on every PR, push and weekly (97.6% success on main) and triggers the downstream eic_container and benchmark pipelines, but it never runs ctest, so the project's own tests are not executed.

Gaps to the next level

• The build-test job runs cmake --build build -- install only; the write_events/read_events ctest tests are never executed.
• The downstream eicweb/eic_container and benchmark statuses failed on the assessed commit and are not required checks.
• The legacy .gitlab-ci.yml targets a master branch and the retired juggler pipeline and does not run.

Actions

• high S Add ctest --test-dir build --output-on-failure to the run: block of the build-test step in .github/workflows/linux-eic-shell.yml.
• low S Delete the unused .gitlab-ci.yml.

The only tests are a write/read round trip of one RawTrackerHit collection out of 52 defined types, and CI does not run them.

Gaps to the next level

• Tests cover one of 52 datatypes and components; the utils headers (vector_utils.h, analysis_utils.h) have no tests.
• Tests are not run in CI.
• No backward-compatibility test that reads files written by earlier releases (issue

Actions

• high S Run ctest in linux-eic-shell.yml (see eng.ci) so the existing round-trip test gates every PR.
• medium M Extend test/write_events.h and test/read_events.h to write and read back one object of every datatype and link type.
• medium S Add unit tests for utils/include/edm4eic/vector_utils.h and analysis_utils.h.

No formatter, linter, static analyzer or pre-commit configuration exists, and no warning flags are set in the CMake files.

Gaps to the next level

• No .clang-format, .clang-tidy, .pre-commit-config.yaml or YAML lint for edm4eic.yaml.
• No compiler warning flags; utils/CMakeLists.txt only disables warnings for edm4eic_event_merge.

Actions

• high S Add .pre-commit-config.yaml with clang-format for utils/ and test/ and a YAML linter for edm4eic.yaml, and enable pre-commit.ci.
• high S Add -Wall -Wextra to the write_events, read_events and generated datamodel targets.

The data model is generated by podio from one YAML file, built with C++20 through CMake, and installs exported EDM4EIC:: targets with a package config; the installed config does not declare its dependencies and no architecture document exists beyond the type diagram.

Gaps to the next level

• cmake/EDM4EICConfig.cmake.in does not call find_dependency for podio, EDM4HEP or ROOT, so consumers must locate them first.
• utils/src/event_merge.cpp and its CLI11 lookup are only built for podio < 0.17.4, which the required podio 1.2 excludes (dead code).
• No design or architecture document beyond the README type diagram.

Actions

• medium S Add find_dependency(podio 1.2), find_dependency(EDM4HEP) and find_dependency(ROOT 6) to cmake/EDM4EICConfig.cmake.in.
• low S Remove utils/src/event_merge.cpp and its CMake block, or port it to podio::Frame.

The README gives generic CMake build commands and links a hosted Doxygen site, but names no dependencies or versions, has no eic-shell route, and has no runnable example.

Gaps to the next level

• README does not list podio >= 1.2, EDM4hep >= 0.10.3 or ROOT 6 as dependencies.
• No eic-shell or Spack install route documented.
• No example showing how to read or write EDM4eic collections.

Actions

• medium S Add an "Installation" section to README.md naming podio, EDM4hep and ROOT with minimum versions and the eic-shell and spack install edm4eic routes.
• medium S Add a short C++ and uproot example reading an EDM4eic collection, linked from the README.

Most members in edm4eic.yaml carry inline descriptions with units, Doxygen API docs are generated and deployed to GitHub Pages from main by CI, and the README carries a type-relation diagram; design conventions (covariance coordinate systems, units, links) are not documented.

Gaps to the next level

• No documentation of the data-model conventions (coordinate systems of covariances, parameter ordering), which issues
• 11 components have no Description, and the Doxyfile uses obsolete tags.

Actions

• medium M Add docs/conventions.md covering units, covariance coordinate systems, parameter ordering and the association-to-link transition, and include it in the Doxygen input.

Only a PR template exists; there is no CONTRIBUTING file, at repository or organization level, describing setup, testing, conventions or the schema-version bump.

Gaps to the next level

• No CONTRIBUTING.md describing eic-shell setup, build, ctest and the rule to bump schema_version with the CMake version.
• No issue templates.

Actions

• medium S Add CONTRIBUTING.md covering eic-shell setup, build, ctest, naming and units conventions for new datatypes, and the version-bump rule.
• medium S Add .github/ISSUE_TEMPLATE/ with "new datatype proposal" and "bug report" templates.

Median first response is 0.99 days, but 21 of 25 open issues are older than one year and 12.5% of new issues were labeled.

Gaps to the next level

• More than half of open issues are older than one year (for example
• New issues are not labeled or otherwise triaged.

Actions

• medium S Close or label each of the 21 open issues older than one year, and label every new issue on arrival.

Nine authors from two e-mail domains committed in 24 months and 8.3% of merged PRs came from outside the maintainer group; level 3 needs 10 authors from 3 institutions and 20% external PRs.

Gaps to the next level

• Fewer than 10 authors and fewer than 3 institutions in 24 months.
• External PRs are 8.3% of merged PRs, below 20%.

Actions

• medium M Invite detector and analysis groups that propose datatypes in issues (for example

Bus factor (50%) is 2 with a top-author share of 43.2%, six people reviewed and two merged in 12 months, and CODEOWNERS assigns edm4eic.yaml to the @eic/epic-admin team; bus factor 3 is not met.

Gaps to the next level

• Bus factor (50%) is 2, below 3.
• CODEOWNERS names a team whose membership is not publicly listed; CMake, utils and tests have no owners.
• Release procedure (version bump in CMakeLists.txt and schema_version, tag, eic-spack update) is not documented.

Actions

• medium S Extend .github/CODEOWNERS to cover CMakeLists.txt, utils/ and test/ with two named maintainers each.
• medium S Add RELEASING.md describing the version bump, tag, GitHub release and eic-spack update.

The approving team for edm4eic.yaml is identifiable from CODEOWNERS and datatype proposals are discussed in public issues, but there is no documented decision process or path to maintainership.

Gaps to the next level

• No governance document stating who approves data-model changes and how.
• No milestones or roadmap; open proposals (#111,

Actions

• medium S Add GOVERNANCE.md stating that the ePIC admin team approves schema changes, how proposals are decided, and how one becomes a maintainer.

No code of conduct exists in the repository or the eic/.github organization repository, and the README names no support channel.

Gaps to the next level

• No code of conduct with a reporting contact.
• No documented support channel.

Actions

• high S Add CODE_OF_CONDUCT.md (or link the ePIC collaboration code of conduct) with a reporting contact.
• high S Add a "Getting help" section to README.md linking the ePIC Mattermost channel for the data model.

The eic-spack recipe carries every release through 8.10.0, which was added on the release day, and eic-shell ships 8.10.0.

Twelve releases in 24 months, all with generated notes, but no version scheme is documented and minor releases carry breaking changes (C++20 requirement in 8.7.0, TrackParameters theta/phi swap in 8.10.0).

Gaps to the next level

• No documented version scheme; edm4eic.yaml only defines the schema-version encoding and patch invariance.
• No changelog or migration notes for breaking changes; no release workflow.

Actions

• medium S State in README.md which changes require a major, minor or patch bump, and follow it for schema-breaking changes.

podio (1.2), EDM4hep (1.0 or 0.10.3) and ROOT (6) are found with minimum versions and Dependabot updates actions, but CLI11 is looked up without a version only for unreachable code and the installed config does not propagate dependencies.

Gaps to the next level

• find_package(CLI11 CONFIG) has no version and serves only code gated on podio < 0.17.4.
• Installed EDM4EICConfig.cmake declares no dependencies; issue
• eic/run-cvmfs-osg-eic-shell@main is pinned to a branch; no SECURITY.md.

Actions

• medium S Remove the CLI11 lookup with the dead event_merge target and add find_dependency calls to cmake/EDM4EICConfig.cmake.in.

CI builds in the eic_xl:nightly image and podio records the schema version in output files, but the image is unpinned and no environment for building or using a release is documented.

Gaps to the next level

• The eic-shell version that each release is built and tested with is not documented.
• No pinned container image in CI.

Actions

• medium S Document in README.md the eic-shell release that first ships each EDM4eic version, and add a CI job pinned to the current stable eic-shell.

CI builds only on Linux x86_64 with the eic-shell default compiler; no site paths are present, but Clang, aarch64 and macOS are untested even though CMakeLists.txt has an Apple branch.

Gaps to the next level

• Only one OS, architecture and compiler is tested.

Actions

• medium S Add a matrix to build-test in linux-eic-shell.yml that also builds with CXX=clang++ and on ubuntu-24.04-arm.

The model extends EDM4hep through podio and is itself reused by EICrecon, algorithms and juggler, but it defines its own ReconstructedParticle, Vertex, Cluster, CalorimeterHit, TrackerHit, Track and Cov2f-Cov6f types alongside EDM4hep equivalents, and keeps its own association datatypes next to podio links, without per-type justification.

Gaps to the next level

• Types duplicating EDM4hep (ReconstructedParticle, Vertex, Cluster, CalorimeterHit, Cov3f/4f/6f) have no documented justification.
• MCRecoAssociation datatypes remain alongside the podio-based MCRecoLink types (issue

Actions

• medium M Document, per datatype that has an EDM4hep counterpart, why the EDM4eic version is needed, or replace it with the EDM4hep type.
• medium M Deprecate and schedule removal of the MCReco*Association datatypes in favor of the link types.

The project defines the EIC-standard podio/EDM4eic schema, declares schema_version and checks it against the CMake version at configure time; the round-trip test covers one type, is not run in CI, and files from older versions are reported unreadable.

Gaps to the next level

• Round-trip I/O test covers only RawTrackerHit and does not run in CI.
• Reading files written by older schema versions is not tested (issues

Actions

• medium M Add a CI job that reads a stored file from the previous release with the PR build, using podio schema evolution.

CI builds in eic_xl:nightly through eic/run-cvmfs-osg-eic-shell every PR and week, but the README does not document building or using EDM4eic in eic-shell and no stable release is tested.

Gaps to the next level

• README has no eic-shell instructions.
• CI tests only the nightly image, not a pinned stable eic-shell release.

Actions

• medium S Add an eic-shell section to README.md (EDM4eic is preinstalled; building a development version inside eic-shell).
• medium S Add a matrix entry with platform-release: eic_xl:<current stable> to build-test in linux-eic-shell.yml.

It requires podio 1.2 and EDM4hep 1.0 against the podio 1.8 and EDM4hep 1.1 that eic-shell ships, builds weekly against the nightly, and added EDM4hep 1.0 support one day after its release; build logs show no deprecation warnings from podio or EDM4hep.

LGPL-3.0 is detected and source files carry SPDX headers, but LICENSE.spdx describes the Juggler package, tests and EDM4eicVersion.h.in are Apache-2.0, and the EDM4hep-derived sections of edm4eic.yaml are not identified.

Gaps to the next level

• LICENSE.spdx names PackageName Juggler and the juggler homepage.
• Third-party content (EDM4hep-derived datatypes, MIT-licensed docs/doxygen-awesome.css) is not recorded in a license inventory.
• No documented contribution terms (inbound = outbound or DCO).

Actions

• low S Correct LICENSE.spdx to describe EDM4eic, and add REUSE metadata recording the Apache-2.0 and MIT files.
• low S State inbound = outbound licensing in a CONTRIBUTING.md.

Zenodo mints a DOI for each release since v8.3.0 under concept DOI 10.5281/zenodo.17242837 with 17 creators, and datatypes carry Author fields; there is no reference publication and the README does not show the DOI.

Gaps to the next level

• No reference publication or software paper.
• No CITATION.cff; the README does not link the DOI.

Actions

• medium M Add CITATION.cff with the concept DOI and a DOI badge in README.md, and cite an EDM4eic description in an ePIC software publication.

EDM4eic ships in eic-shell and is a dependency of EICrecon, algorithms and juggler, so it is part of the ePIC reconstruction and simulation-campaign output.

CODEOWNERS assigns approval of edm4eic.yaml to the @eic/epic-admin team in the ePIC organization, but no multi-institution maintenance commitment or succession plan is documented.

Gaps to the next level

• The README does not name the owning ePIC body, maintainers or their institutions.
• No succession or transition plan.

Actions

• medium S State in README.md the owning ePIC body, the maintainers' institutions and what happens when a maintainer leaves.