epic-capybara is shipped in eic-shell and runs in the CI of EICrecon, epic, npsim and eic/containers, and its default-branch CI includes an end-to-end comparison of EICrecon artifacts that succeeded on all recent runs. Knowledge is concentrated (bus factor 1, 3 authors from 1 e-mail domain in 24 months, 35% of merged PRs reviewed by a non-author), and the only unit test (a doctest) is not run in CI. There is no linter or formatter, no CONTRIBUTING, code of conduct, governance or citation metadata, and dependencies are mostly unversioned with requires-python = ">=3.7".
Assessment by criterion
Code health & engineering practices 0.8
1
Initial · confidence high
All default-branch changes arrive through squash-merged PRs under an active ruleset, but only 35% of merged PRs in 12 months were reviewed by someone other than the author, below the 50% required for level 2.
Evidence (4)
Gaps to the next level
- The ruleset requires a PR but zero approving reviews, so most PRs are self-merged without review.
- No CODEOWNERS file.
Actions
- medium S Set
required_approving_review_count to 1 in ruleset 5452494 so every PR needs a non-author approval.
1
Continuous integration eng.ci
Initial · confidence high
build.yml runs on every PR and on main, builds the wheel and runs capybara capy/bara on EICrecon artifacts, with all recent default-branch runs succeeding, but it never runs the pytest suite in tests/.
Evidence (3)
Gaps to the next level
- CI does not run
pytest (the tests/ directory is never executed). - No required status check on
main.
Actions
- medium S Add a step to
.github/workflows/build.yml that runs hatch run cov (pytest) on every PR and push to main.
1
Initial · confidence high
The only test file runs the doctests of epic_capybara/util.py; capy, bara, cate, github.py and filesystem.py have no unit tests, and the tests are not run in CI.
Evidence (3)
Gaps to the next level
- No unit tests for the majority of modules (
bara.py statistics, key normalisation, capy artifact download). - Doctests in
bara.py (_normalize_key) are not collected by the test suite. - Tests are not executed in CI.
Actions
- medium M Add pytest tests for
bara that compare two small ROOT files (for example from scikit-hep-testdata) and assert p-values and generated report files. - low S Enable
--doctest-modules for the epic_capybara package so bara.py doctests run.
0
Absent · confidence high
No formatter, linter or type checker is configured in the repository or its workflows.
Evidence (2)
files.python_lint = []files.pre_commit = []
Gaps to the next level
- No formatter or linter (ruff, black, flake8) and no pre-commit configuration.
Actions
- high S Add
.pre-commit-config.yaml with ruff and ruff-format and enable pre-commit.ci on the repository.
1
Architecture & language standards eng.modularity
Initial · confidence medium
The package is split into CLI modules and helpers and installs through pyproject.toml with entry points, but it declares requires-python = ">=3.7" (below the 3.9 threshold) and bara is one 500-line function.
Evidence (3)
Gaps to the next level
- Declared Python floor (3.7) and test matrix (3.7 to 3.11) are outdated.
- Histogramming, statistical tests and report rendering are interleaved in the single
bara() function.
Actions
- medium S Raise
requires-python to >=3.10 and update the classifiers and tool.hatch.envs.test.matrix accordingly. - low M Split
bara() into separate functions for reading, statistical comparison and report rendering.
Documentation & usability 1.0
1
Initial · confidence high
The README gives a from-source install with Hatch and points to --help, but names no dependencies or versions, has no eic-shell route, no runnable example with input files, and documents nonexistent "legacy scripts".
Evidence (1)
Gaps to the next level
- No mention that
capybara is available in eic-shell, and no pip install epic-capybara route. - No runnable quick-start example with sample input files.
- The "Legacy scripts" section refers to
capy.py and bara.py, which do not exist at the repository root.
Actions
- medium S Rewrite the README install section to cover eic-shell,
pip install epic-capybara, and from-source, and add a capybara bara a.root b.root --serve example with sample files.
1
Developer & API documentation doc.developer
Initial · confidence high
A few helpers carry docstrings (skip_common_prefix, _normalize_key, _ad_rng), but the CLI commands and github.py are undocumented and there is no API reference or architecture overview.
Evidence (2)
Gaps to the next level
- No generated API documentation.
- No description of the capy/bara/cate data flow or of the statistical tests used.
Actions
- medium S Add
docs/architecture.md describing the capy → bara → cate flow and the KS/Anderson-Darling tests, and add docstrings to the CLI commands.
1
Initial · confidence medium
The README shows how to run the development version with Hatch and the EIC organization supplies PR and issue templates, but there is no CONTRIBUTING file covering tests, conventions or the PR process.
Evidence (3)
Gaps to the next level
- No
CONTRIBUTING.md describing environment setup, running tests, and coding conventions.
Actions
- medium S Add
CONTRIBUTING.md covering eic-shell or Hatch setup, hatch run cov, commit-message conventions and the review process.
1
Initial · confidence low
All 3 issues opened in 12 months came from a maintainer and none is labeled; 4 of 6 open issues are older than one year, which exceeds the half allowed at level 2.
Evidence (4)
Gaps to the next level
- More than half of open issues are older than one year (issue 22 appears addressed by PR 23 but remains open).
- Issues are not labeled or otherwise triaged.
Actions
- medium S Close resolved issues (for example 22) and apply the existing
bug/enhancement labels to all open issues.
1
Initial · confidence high
Three authors were active in 24 months, all from one e-mail domain, with no new authors in 12 months and no external PRs.
Evidence (4)
git.authors_24m = 3git.email_domains_24m = 1git.new_authors_12m = 0prs.external_fraction_12m = 0.0
Gaps to the next level
- Fewer than 4 active authors in 24 months, and no evidence of more than one institution.
Actions
- high M Recruit a co-developer from another ePIC institution (for example among the EICrecon or epic CI users) and label newcomer issues as
good first issue.
1
Knowledge concentration (bus factor) com.bus-factor
Initial · confidence high
The top author wrote 61% of commits in 24 months (bus factor 1) and made all 3 releases, while 3 people review and merge.
Evidence (4)
git.bus_factor_50_24m = 1git.top_author_share_24m = 0.607prs.distinct_mergers_12m = 3releases.authors_24m = 1
Gaps to the next level
- Bus factor (50%) is 1.
- No CODEOWNERS or maintainer list naming at least 2 people.
Actions
- high S Add
.github/CODEOWNERS naming two maintainers for epic_capybara/ and .github/workflows/.
1
Initial · confidence medium
A maintainer is identifiable from the pyproject.toml authors list and the eic-spack recipe, but there is no documented decision process, maintainer path, roadmap or milestones.
Evidence (2)
Gaps to the next level
- No governance document describing who decides and how to become a maintainer.
Actions
- medium S Add a "Maintainers and governance" section to the README naming the maintainers, the owning ePIC group, and the decision process.
1
Code of conduct & user support com.conduct
Initial · confidence medium
The EIC organization issue-template configuration links the ePIC Mattermost and software meetings as support channels, but no code of conduct applies at repository or organization level.
Evidence (2)
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 its reporting contact.
Infrastructure & distribution 1.2
2
Established · confidence high
PyPI provides the latest release 1.2.0 and the package ships in eic-shell, but the eic-spack recipe only offers main and eic-shell pins a commit that predates v1.1.0 and v1.2.0.
Evidence (4)
Gaps to the next level
- The eic-spack recipe has no versioned releases, so eic-shell is not updated per project release.
Actions
- medium S Add
version("1.2.0", ...) (and later releases) to the eic-spack py-epic-capybara recipe and require it in eic/containers packages.yaml.
1
Initial · confidence high
Three releases with generated notes were made between July and August 2026 and none in the preceding 12 months, and no version scheme is documented.
Evidence (3)
Gaps to the next level
- No documented version scheme (SemVer or CalVer).
- Releases do not cover the 24-month window at 2 per year.
Actions
- medium S State in the README that releases follow SemVer and tag a release at least every six months.
Dependencies are declared in pyproject.toml, but only bokeh (and uproot in the rntuple extra) carry minimum versions; Dependabot covers GitHub Actions only, which are not SHA-pinned.
Evidence (3)
Gaps to the next level
- No minimum versions for
awkward, click, hist, PyGithub, requests, scipy, uproot, although bara.py uses version-dependent SciPy APIs (PermutationMethod(rng=...)).
Actions
- medium S Add tested minimum versions to every entry in
[project] dependencies in pyproject.toml.
1
Initial · confidence low
pyproject.toml and the Hatch environment declare the dependency set and Anderson-Darling subsampling uses per-key deterministic seeds, but there is no lockfile, container or documented eic-shell version.
Evidence (2)
Gaps to the next level
- No machine-readable pinned environment (lockfile, container image, or eic-shell version).
- Reports do not record the epic-capybara or dependency versions used.
Actions
- medium S Document the eic-shell version in which each release is tested and write the capybara version into the generated
index.html.
1
Portability & heterogeneous computing dist.portability
Initial · confidence high
CI runs only on ubuntu-latest with the runner's default Python; no other Python version or OS is tested, and no site-specific paths were found.
Evidence (2)
ci.runs_on = [ubuntu-latest]code.site_specific_paths = []
Gaps to the next level
- Only one Python version and one OS are tested.
Actions
- medium S Add a Python-version matrix (for example 3.10 and 3.13) with
actions/setup-python to the build job in build.yml.
EIC ecosystem integration 2.0
3
Reuse of EIC-supported components eic.reuse
Sustained · confidence high
Reading of podio TTree and RNTuple files uses uproot and awkward with no parallel implementations, and the tool is reused by the CI of EICrecon, epic, npsim and eic/containers.
Evidence (3)
Data formats & interoperability eic.data-model
Established · confidence medium
Inputs are EDM4hep/EDM4eic podio ROOT files (TTree or RNTuple) read via uproot; outputs are an HTML report, not physics data; no data-model version is checked.
Evidence (2)
Gaps to the next level
- No check of the podio or EDM4eic version of input files.
- No tests reading TTree and RNTuple inputs.
Actions
- medium S Read the podio/EDM4eic version from the input file metadata, print it in the report, and warn when the two inputs differ.
1
Initial · confidence high
The package ships in eic-shell and is run there by downstream CI, but its own CI runs on a plain ubuntu-latest runner and the README does not document eic-shell use.
Evidence (2)
ci.uses_eic_shell = falsepackaging.in_eic_shell = true
Gaps to the next level
- CI does not build or test in an eic container image.
- The README does not document building or running in eic-shell.
Actions
- medium S Add a job to
build.yml that installs and runs capybara bara inside eic-shell with eic/run-cvmfs-osg-eic-shell.
2
Currency with the EIC stack eic.currency
Established · confidence medium
The current eic-shell ships the package and the EICrecon eic-shell CI runs it, so it is compatible with the current stack; there is no nightly eic-shell CI and eic-shell pins a commit from before v1.1.0.
Evidence (3)
Gaps to the next level
- No CI against eic-shell nightly to catch incompatibilities with new uproot, awkward or podio releases.
- eic-shell does not ship the latest release (v1.2.0).
Actions
- medium S Add an eic-shell nightly job (
platform-release set to eic_xl:nightly) to build.yml.
Impact & long-term viability 1.5
2
Established · confidence high
The MIT license is detected by GitHub and declared in pyproject.toml; SPDX headers appear only in some files and there are no contribution terms.
Evidence (3)
Gaps to the next level
- SPDX headers are missing from
bara.py, capy.py, cate.py, util.py, github.py and filesystem.py. - No documented contribution terms (inbound = outbound or DCO).
Actions
- low S Add
SPDX-License-Identifier MIT headers to all source files and state inbound = outbound licensing in a CONTRIBUTING file.
0
Absent · confidence high
There is no CITATION.cff, .zenodo.json, codemeta, DOI or citation request in the README.
Gaps to the next level
- No citation metadata or software DOI.
Actions
- high S Add
CITATION.cff listing all contributors and enable the Zenodo-GitHub integration for releases.
3
Adoption & downstream use via.adoption
Sustained · confidence high
The package ships in eic-shell and is part of the regression checks in the CI of EICrecon, epic, npsim and the eic/containers cross-architecture comparison.
Evidence (4)
Institutional backing & continuity via.support
Initial · confidence medium
The repository is hosted in the eic organization with copyright held by "Electron-Ion Collider (EIC) Software", but no ePIC body is named as owner and no funding or institutional commitment is stated.
Evidence (2)
Gaps to the next level
- Maintenance responsibility is not assigned to an EIC or ePIC working group in the documentation.
Actions
- high S State in the README which ePIC software working group owns epic-capybara and the maintainers' institutions.