Firebird

90% of first-parent commits in 12 months came from PRs and 57% of merged PRs were reviewed by a non-author, but branch protection requires zero approvals and admins can bypass the ruleset.

Gaps to the next level

• Fewer than 90% of merged PRs are reviewed; PR 137 (467 files changed) was self-merged without a human review.
• Branch protection sets required_approving_review_count to 0 and there is no CODEOWNERS file.

Actions

• medium S Set required_approving_review_count to 1 on main and remove the always-bypass for the admin role in ruleset 10656024.
• medium S Add .github/CODEOWNERS assigning firebird-ng/, packages/, pyrobird/ and dd4hep-plugin/ to at least two reviewers.

Three workflows run the frontend suites, pytest on Python 3.10-3.14 and a build-plus-server integration test on every PR and push, with 97% default-branch success; the DD4hep plugin is not built and the required checks are stale.

Gaps to the next level

• The dd4hep-plugin/ CMake project is not built in any workflow.
• Ruleset 10656024 requires integration-tests (3.8) and (3.9), which no longer exist, and does not require test-and-build or test (*).

Actions

• medium S Update the required status checks in ruleset 10656024 to the current test-and-build, test (3.x) and integration-tests (3.x) job names.
• medium M Add a job that builds dd4hep-plugin/ and runs ddsim with firebird_steering.py for a few events.

Vitest specs cover the core, root2dex, library and pack packages and pytest covers most pyrobird modules, with a server integration test and a root2dex/pyrobird parity test against reference DEX files; coverage is not published and 14% of merged PRs touch tests.

Gaps to the next level

• Test coverage is not measured or published.
• Fewer than 40% of merged PRs in 12 months touch test files.
• The DD4hep plugin has no tests.

Actions

• medium S Run coverage run -m pytest and vitest --coverage in CI and upload the reports to Codecov.
• low S Require a test change in PRs that change pyrobird/pyrobird/ or packages/*/src/, stated in the PR template.

CodeQL default setup analyses every PR and TypeScript compiles with strict, but no formatter or linter (Prettier, ESLint, ruff) is configured, and qodana.yaml is not run in CI.

Gaps to the next level

• No formatter is configured or enforced for TypeScript, Python or C++.
• The CodeQL check failed on PR 137, which was merged anyway.

Actions

• high S Add .pre-commit-config.yaml with ruff, ruff-format, prettier and clang-format and enable pre-commit.ci.

The code is split into npm workspace packages with public-api.ts entry points, published as @dexvis/* on npm, a pyproject-based Python package with a CLI, and a C++20 DD4hep plugin built with CMake; the architecture is documented in docs/extensions.md, docs/design.md and CLAUDE.md.

The hosted VitePress site has a pip-based local-run tutorial with downloadable sample data, documents the pyrobird server options, and has a troubleshooting page; the docs are not versioned with releases and no tutorial is executed in CI.

Gaps to the next level

• Documentation is published only for main, not per release.
• The tutorials are not executed in CI.
• The docs do not state that pyrobird is available in eic-shell.

Actions

• medium S Add a CI job that runs the 02_run_local steps (pyrobird serve, fetch the sample files through the API) on the sample data.

Most pyrobird public functions (85 of 102) and the TypeScript API files carry docstrings, and the architecture is described in docs/extensions.md, docs/design.md and CLAUDE.md, but no API reference is generated.

Gaps to the next level

• No generated API documentation (TypeDoc, Sphinx or similar).

Actions

• medium M Generate TypeDoc for packages/* and Sphinx autodoc for pyrobird in docs.yaml and publish them with the VitePress site.

The README covers setup and running the test suites, the pyrobird README states conventions and the PR process, CLAUDE.md lists TypeScript standards, and the organization supplies PR and issue templates; review expectations, newcomer issues and a ready-made environment are missing.

Gaps to the next level

• The guidance is spread over three files with no CONTRIBUTING.md, and review expectations are not documented.
• The good first issue label exists but no issue carries it.
• No devcontainer or eic-shell development environment is documented.

Actions

• medium S Add CONTRIBUTING.md that consolidates setup, tests, conventions and review expectations, and label five newcomer issues good first issue.

The median first response is 0.18 days, but 13 of 19 open issues are older than one year, no issue opened in 12 months is labeled, and 40% received no response.

Gaps to the next level

• More than half of open issues are older than one year.
• New issues are not labeled or otherwise triaged; all 13 open PRs are older than 90 days.

Actions

• medium S Apply the existing [UI]/[pyrobird]/[engine] labels to all open issues and close or update those older than one year.

Four authors were active in 24 months, but only two in 12 months, with no new authors and no merged PRs from outside the maintainer group.

Gaps to the next level

• No external PRs have been merged.
• Institutional spread is not documented (metrics:git.email_domains_24m = 0).

Actions

• high M Recruit a co-developer from another ePIC institution through the ePIC software meetings and merge the open contributor PRs or close them.

The top author wrote 72% of commits in 24 months (bus factor 1); two people review and three merge.

Gaps to the next level

• Bus factor (50%) is 1.
• No CODEOWNERS or maintainer list names at least 2 people.

Actions

• high S Add .github/CODEOWNERS and a maintainers section in the README naming at least two maintainers per component.

The maintainer is identifiable from pyproject.toml and decisions such as the CalVer switch are proposed in public issues, but there is no documented decision process, maintainer path or milestones.

Gaps to the next level

• No document stating who decides and how to become a reviewer or maintainer.

Actions

• medium S Add GOVERNANCE.md naming the maintainers, the owning ePIC group, the decision process and the path to maintainership.

The organization issue-template configuration links the ePIC Mattermost and meetings as support channels, but no code of conduct applies at repository or organization level; GitHub Discussions is enabled with no threads.

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, and a "Getting help" section in the README.

pyrobird is on PyPI and in eic-spack (including 2026.10.0b1) and ships in eic-shell, but eic-shell pins an untagged git commit because 0.2.7 is broken on PyPI, and the DD4hep plugin has no recipe.

Gaps to the next level

• eic-shell does not ship a released version; the last stable PyPI release (0.2.7) is marked broken in eic-spack.
• The eic-spack recipe still depends on py-pyppeteer for +batch, which the project replaced with playwright.
• The DD4hep plugin has no Spack recipe.

Actions

• medium S Publish a stable CalVer release to PyPI, add it to the eic-spack pyrobird recipe (with py-playwright for +batch) and pin it in eic/containers.

Versions are uploaded to PyPI without git tags, GitHub releases or release notes; CalVer was agreed in an issue but is not documented in the repository.

Gaps to the next level

• No tags, GitHub releases, release notes or changelog.
• The version scheme is not documented in the repository.

Actions

• high S Tag each release vYYYY.MM.N, create a GitHub release with generated notes, and state the CalVer scheme in the README.

npm and uv lockfiles exist and Dependabot covers npm and GitHub Actions, but pyrobird's pyproject.toml gives a minimum version only for flask-compress, and CMake requires fmt and Geant4 without versions.

Gaps to the next level

• The published pyrobird package declares no minimum versions for click, rich, pyyaml, flask, flask-cors, json5, uproot.
• find_package(fmt) and find_package(Geant4) have no VERSION.

Actions

• medium S Add tested minimum versions to every [project] dependencies entry and VERSION to the fmt and Geant4 find_package calls.

pyrobird/uv.lock and package-lock.json pin the environment and CI installs from them, but converted DEX files record only the input file and entry count, not the pyrobird version or conversion options.

Gaps to the next level

• DEX outputs do not record the converter version or configuration (cuts, box size, steering parameters).
• No eic-shell version is documented for the DD4hep plugin or releases.

Actions

• medium S Write the pyrobird or plugin version and the conversion or steering options into the DEX origin object.

pyrobird is tested on Python 3.10-3.14 with no site-specific paths in the code; CI runs only on ubuntu-latest with one Node.js version, though package.json declares Node 22, 24 and 26.

Gaps to the next level

• No macOS or aarch64 CI job, although issue 57 reports a macOS-specific problem.
• Only one of the declared Node.js versions is tested.

Actions

• medium S Add macos-latest and ubuntu-24.04-arm jobs and a Node 22/24 matrix to frontend.yaml and pyrobird.yaml.

Event input is read from EDM4eic/EDM4hep podio files with uproot, geometry comes from the epic TGeo export, and trajectories are recorded with DD4hep DDG4 actions; the DEX JSON format is documented as the browser exchange format, and no upstream contributions or reuse by other EIC software were found.

Gaps to the next level

• No extension contributed upstream (for example the trajectory writer to DD4hep or npsim) and no EIC repository reuses a Firebird component.

Actions

• low M Offer the trajectory-writer action to npsim or DD4hep DDG4 so it ships with the simulation stack.

Inputs are EDM4eic/EDM4hep podio ROOT files and TGeo geometry; the DEX output format has a published JSON Schema, a declared version that collect_dex_problems checks, and upgrade round-trip and schema tests; the EDM4eic/EDM4hep version of inputs is not read or checked.

Gaps to the next level

• The podio/EDM4eic/EDM4hep version of input files is not checked; branch-name differences are handled by detection.

Actions

• medium S Read the podio and EDM4eic/EDM4hep versions from the input file metadata in pyrobird and root2dex, record them in DEX origin, and warn on unsupported versions.

pyrobird ships in eic-shell and the plugin docs show building in eicweb/eic_xl:nightly, but no CI job runs in an eic container image.

Gaps to the next level

• CI does not build or test the plugin or pyrobird in an eic container image.

Actions

• medium S Add a workflow using eic/run-cvmfs-osg-eic-shell that builds dd4hep-plugin/, runs npsim with firebird_steering.py, and runs pyrobird convert on the output.

The current eic-shell builds pyrobird (git commit 25b6556) and the plugin requires DD4hep 1.27 or later against the shipped 1.38, with no open stack-incompatibility issues; there is no nightly eic-shell CI, and eic-shell has not picked up the October 2026 rewrite.

Gaps to the next level

• No CI against eic-shell nightly to catch DD4hep, Geant4 or uproot changes.

Actions

• medium S Add an eic-shell job with platform-release set to eic_xl:nightly that builds the plugin and runs the pyrobird tests.

GPL-3.0-or-later is detected by GitHub and declared in pyproject.toml, the MIT packages carry their own LICENSE and license fields, and the README explains the split; there are no SPDX headers or contribution terms.

Gaps to the next level

• No SPDX-License-Identifier headers in source files.
• No documented contribution terms (inbound = outbound or DCO).
• The eic-spack recipe declares LGPL-3.0-or-later, which differs from the project license.

Actions

• low S Add SPDX headers (GPL-3.0-or-later or MIT per directory) and run reuse lint in CI.

There is no CITATION.cff, .zenodo.json, codemeta, DOI or citation request.

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 tagged releases.

pyrobird ships in eic-shell (with +xrootd), and the EIC website links the Firebird deployment as its event display.

The repository is in the eic organization and the main maintainer's public profile lists an institution, but the documentation names no owning ePIC body, funding or institutional commitment.

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 the owning ePIC working group, the maintainers' institutions and any funding.