EDM4hep

58.5% of merged PRs have a non-author review, but only 74.7% of first-parent commits came from PRs; maintainers push release-note, version-bump and CI changes directly to main, below the 80% needed for level 2.

Gaps to the next level

• 19 of 75 first-parent commits in 12 months bypassed PRs (release notes, version bumps, CI and CMake config updates).
• The rulesets require a PR but zero approving reviews, and there is no CODEOWNERS.

Actions

• medium S Route release-note, version-bump and Key4hepConfig/CI template updates through PRs and remove maintainer bypass from the main ruleset.
• medium S Set required_approving_review_count to 1 in the "Default branch (Key4hep)" ruleset.

Every PR and push to main builds and runs ctest on four LCG stacks (GCC and Clang, podio main) and on Key4hep release and nightly stacks, as required status checks, with 80% of default-branch runs succeeding. Level 3 is missed on the 90% success rate and on a downstream check that failed on 8 of its last 10 runs and is not required.

Gaps to the next level

• Default-branch success rate is 80% (scheduled Key4hep nightly builds fail intermittently), below 90%.
• The downstream-build workflow failed on 8 of its last 10 runs (the others cancelled or awaiting approval) and is not a required check.

Actions

• medium M Fix the downstream-build job (key4hep-actions/downstream-build) so it passes, and add it to the ruleset's required status checks.

Catch2 unit tests cover the utils, write/read round trips cover every datatype in ROOT, SIO and RNTuple, and backwards-compatibility tests read reference files written by four earlier releases. Coverage is not measured and 37.7% of merged PRs touch tests, below 40%.

Gaps to the next level

• Test coverage is neither measured nor published (metrics:files.codecov is empty).
• Fewer than 40% of merged PRs in 12 months touch test files.

Actions

• medium M Add a gcov/lcov build to .github/workflows/lcg_linux_with_podio.yml and upload the report to Codecov.
• low S Add a PR-template checkbox asking for a test with each schema or utility change.

clang-format, ruff and ruff-format run through pre-commit on every push and PR as a required check, and the build enables -Wall -Wextra -Wpedantic -Wshadow -Wdeprecated. No clang-tidy, sanitizer or other deeper analysis runs, and warnings do not fail CI.

Gaps to the next level

• No clang-tidy, cppcheck or sanitizer job runs in CI.
• Compiler warnings are not treated as errors or tracked to zero.

Actions

• medium S Add an ASan/UBSan build of the ctest suite to .github/workflows/lcg_linux_with_podio.yml.

The schema is generated by podio into separate core, dictionary, SIO, Arrow, utils, RDF and tool targets, built with C++20 and exported as the EDM4HEP:: CMake package, which CI verifies by building a downstream project. Public headers live under include/ and utils/include/, and the README diagram and Doxygen pages document the type structure.

The README gives a Key4hep-stack build, a Python quick start and edm4hep2json usage, and Doxygen pages are hosted. The dependency list omits nlohmann_json, Python and Catch2, and the CMake options are not documented.

Gaps to the next level

• README omits required dependencies nlohmann_json (>= 3.10.5, on by default), Python 3 and Catch2 v3, and CMake >= 3.23.
• CMake options (EDM4HEP_WITH_JSON, BUILD_DOCS, USE_EXTERNAL_CATCH2) are not documented for users.
• README still describes the project as "beta" and points to a tests directory that is named test.

Actions

• medium S Extend the README "Dependencies" section with every find_package dependency and minimum version, and add a table of CMake options.

Every datatype and member in edm4hep.yaml carries a description that becomes Doxygen output, published at edm4hep.web.cern.ch, and doc/ holds design notes (PIDHandler, vertices, LCIO differences). The publishing pipeline runs on a CERN GitLab mirror whose runs are not public, and several utility headers have no per-function documentation.

Gaps to the next level

• The Doxygen deployment runs on a CERN GitLab mirror with no publicly visible pipeline.
• vector_utils.h and cov_matrix_utils.h have almost no Doxygen comments on their public functions.

Actions

• medium S Move the Doxygen build and deployment into a public GitHub Actions workflow (for example to GitHub Pages) triggered on main and tags.
• low S Add Doxygen comments to every public function in utils/include/edm4hep/utils/vector_utils.h and cov_matrix_utils.h.

doc/contributing.md and the Key4hep organization CONTRIBUTING describe the fork-and-rebase workflow and the release-notes block, and issue and PR templates exist. Neither documents running the tests, the clang-format/ruff pre-commit setup, or the coding conventions beyond "no new warnings".

Gaps to the next level

• Contribution guidance does not cover environment setup, running ctest, or pre-commit/clang-format conventions.
• doc/contributing.md still refers to the master branch.

Actions

• medium S Extend doc/contributing.md with Key4hep-stack setup, ctest invocation, pre-commit install, and the clang-format/ruff conventions.

Median first response is 1.3 days and 13 of 17 new issues were labeled or closed, but 12 of 20 open issues are older than a year and no triage process is documented.

Gaps to the next level

• 60% of open issues are older than one year (level 3 needs under 25%).
• No documented triage process; no milestones are used.

Actions

• medium S Review the 12 open issues older than one year, close or label them, and document the label scheme in doc/contributing.md.

11 authors from 3 e-mail domains contributed in 24 months, with 3 new authors in 12 months and external PRs merged, but only 7.5% of merged PRs came from outside the maintainer group.

Gaps to the next level

• External contributors account for 7.5% of merged PRs (level 3 needs 20%).

Actions

• low S Label open enhancement issues such as utility requests with good first issue and link them from the README.

Bus factor (50%) is 2, 3 people reviewed and 2 merged, releases were cut by 2 people, and the upstream Spack recipe names 3 maintainers. Level 3 is missed on the bus factor and on the absence of named per-component owners.

Gaps to the next level

• Bus factor (50%) is 2; level 3 needs 3.
• No CODEOWNERS or in-repository maintainer list; the release procedure is not documented.

Actions

• medium S Add .github/CODEOWNERS naming two owners each for edm4hep.yaml, utils/, tools/ and python/.

Maintainers can be identified through CITATION.cff and the Spack recipe, and schema decisions are discussed in public issues labeled discussion, but no decision process, maintainer path or roadmap is documented.

Gaps to the next level

• No documented decision process or path to reviewer or maintainer.
• No roadmap or milestones.

Actions

• medium S Add GOVERNANCE.md naming the maintainers, how schema changes are decided (issue discussion, Key4hep meetings with linked minutes), and how to become a maintainer.

The issue tracker is documented as the support channel, but no code of conduct is linked from the repository; the Key4hep documentation carries a Contributor Covenant 1.0 text without a specific reporting contact.

Gaps to the next level

• No code of conduct with a reporting contact applies to or is linked from the repository.

Actions

• high S Add CODE_OF_CONDUCT.md to the key4hep .github repository with a named reporting contact so it applies to EDM4hep.

Upstream Spack provides the latest release 1.1.1, added the day v01-01-01 was tagged, and eic-shell ships EDM4hep 1.1 (the collector's latest_release_packaged = false reflects the v01-01-01 tag naming).

Six releases in 24 months each have notes, and doc/ReleaseNotes.md flags breaking changes and deprecations, but no version scheme is documented.

Gaps to the next level

• The vXX-YY-ZZ version scheme and its compatibility meaning are not documented.
• No deprecation policy and no public release workflow.

Actions

• medium S State in the README that tags follow SemVer as vMM-mm-pp and what a major, minor or patch bump means for schema and API compatibility.

podio, nlohmann_json and HepMC3 are declared with minimum versions, but ROOT, Python3 and HepPDT have no version constraint in CMake, and there is no Dependabot or Renovate configuration.

Gaps to the next level

• find_package(ROOT), find_package(Python3) and find_package(HepPDT) have no minimum version, although the README states ROOT >= 6.22/06.
• No automated dependency update monitoring; key4hep-actions/*@main and actions/checkout@v4 are not pinned.

Actions

• medium S Add VERSION arguments to the ROOT, Python3 and HepPDT find_package calls matching the README.

CI builds in Key4hep container images against Key4hep release and nightly stacks, the README documents the CVMFS stack setup, and files record and tests check the EDM4hep and podio versions. The documented environment is the unpinned nightly, and no release names the stack or image it was built and tested with.

Gaps to the next level

• No release states the Key4hep stack or container tag it was validated in.

Actions

• medium S Record in each release note the Key4hep release stack and key4hep-images tag used by the release CI run.

CI builds and tests with GCC 13 and Clang 22 on AlmaLinux 9, Ubuntu 24.04 and 26.04, with no site-specific paths, but only on x86_64 Linux.

Gaps to the next level

• No aarch64 or macOS job in CI.
• No statement on accelerator use or why it does not apply.

Actions

• medium M Add an ubuntu-24.04-arm job building podio and EDM4hep and running ctest to .github/workflows/lcg_linux_with_podio.yml.

The data model is generated and serialized by podio and uses ROOT and HepMC3, with no parallel implementations, and it is itself the base that EDM4eic and EICrecon build on.

EDM4hep defines the EIC-standard event format in podio ROOT, RNTuple and SIO files; the version is written to files and checked on read, round-trip and backwards-compatibility tests run in CI, and EIC benchmarks read the files with uproot.

eic/containers builds EDM4hep into the eic images and its CI runs npsim and EICrecon on EDM4hep files in them; the project's own CI does not use eic-shell. Only the pinned release is tested in eic images, so EDM4hep changes reach the EIC stack untested until they are released and pinned.

Gaps to the next level

• No CI builds EDM4eic or EICrecon against EDM4hep main before an EDM4hep release.

Actions

• medium M (EIC side) Add a scheduled eic/containers or EDM4eic job that builds EDM4eic and EICrecon against EDM4hep main in eic_ci:nightly.

EDM4hep requires podio >= 1.7 while eic-shell ships podio 1.8, CI builds against podio main on every PR so podio changes are adapted before release, and the latest CI logs show no deprecation warnings from podio or ROOT.

A single Apache-2.0 license is detected and stated in CITATION.cff and the Spack recipe, compatible with podio and ROOT. Source files carry no SPDX headers, the NOTICE file is empty, and the vendored public-domain MurmurHash3 is not recorded.

Gaps to the next level

• No SPDX headers in source files and no record of third-party code (MurmurHash3) in NOTICE.
• No documented contribution terms.

Actions

• low S Add SPDX-License-Identifier headers, list MurmurHash3 in NOTICE, and state inbound = outbound in doc/contributing.md.

CITATION.cff lists 6 authors with a Zenodo concept DOI and the ICHEP 2022 paper, and Zenodo mints a DOI per release (v01-01-01 included). CITATION.cff has no version and was last changed in 2025-09, and lists 6 of the 11 authors active in 24 months.

Gaps to the next level

• CITATION.cff is not updated with each release (no version or date-released).
• Contributors since the 2022 paper are not credited in the citation metadata.

Actions

• medium S Add version and date-released to CITATION.cff in the release-notes commit, and add a .zenodo.json or contributor list covering recent authors.

EDM4hep ships in eic-shell, EDM4eic and EICrecon depend on it, the EIC simulation chain writes EDM4hep files, and it is the event data model of the Key4hep stack used by FCC, CEPC and linear collider studies.

The Key4hep documentation, which covers EDM4hep, acknowledges CERN EP R&D and EU Horizon 2020 funding, and the authors are at CERN and DESY. No multi-institution maintenance commitment or succession plan is documented.

Gaps to the next level

• No documented multi-institution maintenance commitment or succession plan.

Actions

• low S State in the README the institutions committed to maintaining EDM4hep and what happens when a maintainer leaves.