podio

95.5% of first-parent commits arrive through PRs and 67.5% of merged PRs have a review by someone other than the author, below the 90% needed for level 3. Branch protection requires status checks, but no required review, CODEOWNERS, or documented review expectations are visible.

Gaps to the next level

• Fewer than 90% of merged PRs have a review by someone other than the author.
• No CODEOWNERS file or publicly visible required-review rule.
• The PR template contains only the release-notes block, with no review expectations.

Actions

• medium S Require one approving review in the master branch protection rule and add .github/CODEOWNERS.
• low S Add a review checklist (tests, docs, release notes) to .github/PULL_REQUEST_TEMPLATE.

Every PR and push runs ctest on 7 LCG stacks, 2 Ubuntu stacks, 4 Key4hep configurations and 6 sanitizer builds, plus downstream EDM4hep and EDM4eic builds, as required checks. Only 76% of recent default-branch runs succeed, below the 80% needed for level 2; the failures come from the dev3 nightly jobs.

Gaps to the next level

• Fewer than 80% of recent default-branch runs succeed; dev3 nightly jobs (required checks) fail repeatedly.
• macOS, named as a supported platform in the README, is not built in CI.

Actions

• high S Fix or mark continue-on-error the dev3 matrix entries in test.yml, ubuntu.yml and edm4hep.yaml so master stays green (issue

Catch2 unit tests and write/read round-trip tests for the ROOT, RNTuple, SIO and Arrow backends run in CI on every PR, and regression tests read reference files written by older podio releases; 40.4% of merged PRs touch tests. Test coverage is not measured or published.

Gaps to the next level

• Test coverage is neither measured nor published (metrics:files.codecov is empty).

Actions

• medium M Add a gcov/lcov build job to .github/workflows/test.yml and publish results to Codecov.

pre-commit (clang-format, black, flake8, pylint, cppcheck, clang-tidy with warnings as errors) is a required CI check, the CI preset builds with -Werror, and ASan/TSan/UBSan and nightly Coverity run routinely. cppcheck suppresses all findings under tests and two checks globally, and deprecation warnings are exempted from -Werror.

Gaps to the next level

• Blanket cppcheck suppressions (*:*tests*, noExplicitConstructor:*, unusedFunction:*).
• -Wno-error=deprecated-declarations in the CI preset and clang-tidy hook lets deprecation warnings pass.

Actions

• low M Replace the *:*tests* and global *: entries in .cppcheck-suppressions.txt with per-file suppressions.
• low S Remove -Wno-error=deprecated-declarations from the ci-build preset once no deprecation warnings remain.

C++20 is required, the core, I/O backends, code generator and tools are separate components, and an exported podio:: CMake package with data-model macros is installed. Internals are kept in include/podio/detail, and the design is documented in doc/design.md.

The README gives build, test and Spack install steps with ROOT and Python versions, and the hosted docs cover data-model syntax and usage. The required fmt (>= 9) dependency is not listed, Python packages have no versions, and the README points to removed paths.

Gaps to the next level

• fmt (required, >= 9) and optional SIO/Arrow/Parquet are not listed with versions in the install instructions.
• The README references tests/datamodel/ and python/tools/podio-vis, which do not exist.
• Versioned docs are built to gh-pages but not served; no troubleshooting or FAQ page.

Actions

• medium S Add fmt >= 9, optional backends with versions, and minimum pyyaml/jinja2 versions to the README prerequisites.
• medium S Replace the stale tests/datamodel/ and python/tools/podio-vis references with a minimal runnable data-model example.

Public headers carry Doxygen comments, and Sphinx/Breathe generate C++ and Python API references published from master by the CERN GitLab mirror CI. Design, storage layout, frames, links and schema evolution are documented, with references to LCIO and Gaudi.

CONTRIBUTING and doc/contributing.md cover the fork/rebase workflow, PR release-notes format and the no-new-warnings rule; README and doc/advanced_topics.md cover build, ctest and pre-commit; issue and PR templates exist. How to propose larger changes is not documented, and no ready-made development environment is described.

Gaps to the next level

• No documented process for proposing larger changes; review expectations are limited to a note on review time.
• No devcontainer or documented ready-made environment (Key4hep/LCG view or eic-shell) for development.

Actions

• medium S Add sections to .github/CONTRIBUTING.md on RFC issues for larger changes, review expectations, and building in a Key4hep nightly or eic-shell environment.

Median first response is 4.1 days, but 23 of 31 open issues are older than one year and 21% of new issues are labeled, which places the project at level 1.

Gaps to the next level

• More than half of open issues are older than one year.
• Most new issues are not labeled.

Actions

• medium S Review the 23 issues older than one year and close, label, or schedule each.
• medium S Label every new issue on arrival using the existing label set.

13 authors from 3 institutional e-mail domains contributed in 24 months, with 3 new authors and merged external PRs. External PRs are 11.4% of merged PRs, below the 20% needed for level 3.

Gaps to the next level

• Fewer than 20% of merged PRs come from contributors outside the maintainer group.

Actions

• low S Keep good first issue labels current and link them from CONTRIBUTING to attract outside contributors.

Bus factor (50%) is 2 with 5 reviewers and 2 mergers, but no maintainer list or CODEOWNERS names anyone, and one person made all releases in 24 months.

Gaps to the next level

• No maintainer list or CODEOWNERS naming at least 2 people.
• All releases in 24 months were made by one person, and the release procedure is undocumented.

Actions

• high S Add .github/CODEOWNERS naming at least two owners for src/, include/, python/ and tools/.

Decisions are discussed publicly in issues and PRs (for example RFC issue #997), but no document names the maintainers or describes the decision process, and there are no milestones.

Gaps to the next level

• Maintainers are not named in the README, CODEOWNERS, or any governance document.
• No documented decision process or path to becoming a maintainer.

Actions

• high S Add a "Maintainers" section to the README or a GOVERNANCE.md naming the maintainers and their institutions.

The GitHub issue tracker is documented as the support channel, but no code of conduct applies to the repository or the AIDASoft organization.

Gaps to the next level

• No code of conduct with a reporting contact.

Actions

• medium S Add CODE_OF_CONDUCT.md (Contributor Covenant) with a reporting contact, or link the Key4hep or AIDA code.

Upstream Spack provides every release through 1.8 (the latest tag v01-08), added the same day as the release, and eic-shell ships podio 1.8.

Eight releases in 24 months each carry notes generated from PR release-note blocks, and doc/ReleaseNotes.md records history. The vMM-mm-pp version scheme is not documented, and the manual process required re-tagging v01-08 after it reported the wrong version.

Gaps to the next level

• The version scheme and its compatibility promise are not documented.
• No release workflow; the v01-08 tag was moved after publication.

Actions

• medium S State in the README that vMM-mm-pp maps to SemVer MAJOR.MINOR.PATCH and what each component signals for API and file compatibility.

ROOT (6.28.04), fmt (9), nlohmann_json (3.10) and Catch2 declare minimum versions, and CI tests both the minimum ROOT (LCG_104) and nightlies. SIO, Arrow, Parquet and the Python modules in requirements.txt have no version constraints.

Gaps to the next level

• find_package for SIO, Arrow and Parquet and requirements.txt entries carry no minimum versions.

Actions

• medium S Add VERSION arguments to the SIO, Arrow and Parquet find_package calls and minimum versions to requirements.txt.

The README describes the environment in prose (a recent LCG or Key4hep release), and CI pins LCG views in workflow files, but no documented machine-readable environment is provided for users. Written files record the podio build version and the EDM definitions.

Gaps to the next level

• No documented machine-readable environment (container, Spack environment, or pinned Key4hep/eic-shell release) for users.

Actions

• medium S Document per release the Key4hep release or LCG view (and eic-shell tag) it was tested in, and add a spack.yaml environment for development.

CI builds and tests with GCC 13/15/16 and Clang 22 on EL9 and Ubuntu 22.04/24.04, with no site paths. All jobs run on x86_64 Linux, although the README addresses macOS users, and HTC/HPC use is not documented.

Gaps to the next level

• No aarch64 or macOS job in CI.
• No documentation of HTC/HPC use or of why accelerator support does not apply.

Actions

• medium M Add a macos-latest or ubuntu-24.04-arm job that builds and runs ctest to the CI matrix.

podio builds on ROOT and fmt and contains no parallel implementation of other stack components. It is itself the data-model component that EDM4hep, EDM4eic, EICrecon and JANA2 build on.

podio defines the EIC-standard podio ROOT format, documents its layout, writes the podio version and schema versions into files and checks them on read, and tests write/read round trips. EIC tools read podio output with uproot without podio code.

eic/containers builds podio 1.8 into the eic-shell images and runs EICrecon end-to-end with podio output in its CI, and podio's own CI builds and tests EDM4eic against podio master on every PR, but in a Key4hep view. The eic-shell nightly pins podio 1.8, so podio master is never tested in an eic container.

Gaps to the next level

• Neither podio's CI nor eic/containers tests podio master in an eic-shell nightly image.

Actions

• medium S Add a job to .github/workflows/edm4eic.yml that builds podio and EDM4eic in eic_xl:nightly via eic/run-cvmfs-osg-eic-shell.

podio 1.8, the latest release, is the version eic-shell ships, and CI tracks ROOT and compiler nightlies (dev3, dev4), with no deprecation warnings in the build log of the assessed commit. The new ROOT cppjit incompatibility (issue #1038) was reported on the day it appeared.

The project is Apache-2.0, but LICENSE contains only the short notice, so no SPDX identifier is detected, and no package metadata states the license.

Gaps to the next level

• The license is not machine-detectable (no full Apache-2.0 text, no SPDX identifier).

Actions

• high S Replace LICENSE with the full Apache-2.0 text so GitHub detects Apache-2.0, keeping the copyright line in a NOTICE file.

The repository has no CITATION.cff, Zenodo metadata, DOI, or citation request. Proceedings papers on podio exist (arXiv:2312.08206) but are not referenced from the repository.

Gaps to the next level

• No citation information or software DOI.

Actions

• high S Add CITATION.cff listing the authors and the reference paper arXiv:2312.08206, and enable the Zenodo-GitHub integration.

podio ships in eic-shell and is the I/O layer of EDM4eic and EICrecon output used in EIC production; outside EIC it underlies EDM4hep and Key4hep.

Recent authors use DESY, CERN and BNL e-mail domains and docs are hosted on Key4hep CERN infrastructure, but no README or documentation states an institutional commitment or funding.

Gaps to the next level

• No funding acknowledgement or statement of institutional or Key4hep/EIC ownership in the README or docs.

Actions

• medium S State in the README the owning project (AIDASoft/Key4hep), the maintaining institutions and funding sources.