JANA2

84.4% of first-parent commits in 12 months arrived through PRs, but none of the merged PRs had a review from someone other than the author, below the 50% required for level 2.

Gaps to the next level

• No merged PR in 12 months was reviewed by a non-author.
• Branch protection requires no approving review and no status checks; no CODEOWNERS or PR template.

Actions

• high S Require one approving review on master through branch protection or a ruleset, and have a second maintainer review each PR.

Six workflows build and run ctest or the unit-test binary on every PR and push to master (Ubuntu, macOS, eic-shell nightly, a full-dependency container), with EICrecon and GlueX downstream builds, and 88% of recent default-branch runs succeed. Passing CI is not required before merge, and the GlueX integration workflow has failed on every master push since 2026-08-21.

Gaps to the next level

• No required status checks on master (branch protection lists none).
• Default-branch success rate 88%, below 90%; GlueX integration fails on master since 2026-08-21.
• The CUDA platform workflow is disabled by targeting a non-existent branch.

Actions

• medium S Fix the failing test_integration_gluex.yml job and mark the Ubuntu, macOS, dependency-matrix and ePIC workflows as required status checks on master.

Catch2 unit tests cover the Components, Engine, Services, Topology and Utils modules and run in CI on every PR, and end-to-end runs (TimesliceExample, EICrecon on npsim output) exist. There is no coverage measurement, no comparison against reference outputs in CI, and 30.8% of merged PRs touch tests.

Gaps to the next level

• No coverage measured or published.
• No regression test comparing outputs with reference files; the regressiontest plugin is not run in CI.
• 30.8% of merged PRs touch tests, below 40%.
• Calibrations, Geometry and CLI libraries have no unit tests.

Actions

• medium S Add a coverage build (--coverage with lcov or gcovr) to test_platform_ubuntu.yml and publish it to Codecov.
• medium M Add a CI step that compares the TimesliceExample or EICrecon output with a stored reference using epic-capybara.

The project configures no formatter, linter or static analyzer; the only .clang-format and .clang-tidy files belong to vendored pybind11. Compiler warnings (-Wall -Wextra in Debug, -Werror on macOS) and optional ASan/TSan build options exist but are not linters.

Gaps to the next level

• No project formatter or linter configuration.
• No sanitizer or static-analysis job in CI.

Actions

• high S Add a .clang-format matching the documented conventions and a .pre-commit-config.yaml with clang-format, and enable pre-commit.ci on PRs.

CMake builds components (core library, plugins, programs) with C++17 as default, configuration goes through the parameter manager, and an exported JANAConfig.cmake with JANA:: targets is installed. All headers, including Engine and Topology internals, are installed by glob, so public API and internals are not separated.

Gaps to the next level

• Every header under Engine/, Topology/ and Utils/ is installed; no separation of public API from internals.
• The build still accepts C++14.

Actions

• medium M Install only the user-facing headers (or move internals to an internal/ directory excluded from install) and drop C++14 from the accepted standards.

The README and the hosted docs give CMake build-and-run commands, a tutorial and a configuration how-to, but no list of dependencies or minimum versions and no eic-shell or Spack install route.

Gaps to the next level

• Dependencies (CMake 3.16, ROOT, podio, ZeroMQ, Xerces-C, Python) and their versions are not listed.
• No eic-shell or Spack installation route documented.
• The tutorial links to src/examples/Tutorial, which no longer exists.

Actions

• medium S Add a dependency table with minimum versions and an "Installing via eic-shell / eic-spack" section to docs/install.md.

An architecture overview (docs/concepts.md, docs/behavior.md) exists and Doxygen is generated and deployed to Pages by CI, but most public methods lack doc comments (for example JApplicationFwd.h declarations and JComponent.h carry none).

Gaps to the next level

• Most public methods of JApplication, JComponent, JEventUnfolder and JEventProcessor have no Doxygen comments.

Actions

• medium M Add Doxygen comments to every public method in the installed headers of src/libraries/JANA/ starting with JApplication, JComponent, JEventProcessor and JEventUnfolder.

The inherited organization CONTRIBUTING.md gives a generic fork-and-PR note and docs/development/contributing.md lists coding conventions and the release procedure, but neither covers development setup or running the tests, and there are no issue or PR templates.

Gaps to the next level

• No documented development setup or test commands (ctest).
• No issue or PR templates.

Actions

• medium S Add CONTRIBUTING.md covering eic-shell setup, the CMake options used in CI, running ctest, and the PR process, plus .github/pull_request_template.md and issue templates.

6 of 11 issues opened in 12 months (54.5%) received no response, a majority; most of these are maintainer-filed tracking issues, but one external report (#496) is also unanswered. No issue opened in 12 months is labeled and 44 of 50 open issues are older than one year.

Gaps to the next level

• Most issues opened in 12 months have no response.
• No labeling or triage of new issues; 88% of open issues are older than one year.

Actions

• high S Respond to and label every new issue (existing bug/enhancement labels), and close or label the 44 open issues older than one year.

8 authors from 3 e-mail domains committed in 24 months and 15.4% of merged PRs came from outside the maintainer group; fewer than 10 active authors prevents level 3.

Gaps to the next level

• Fewer than 10 active authors in 24 months; external PRs are 15.4% of merges, below 20%.

Actions

• medium M Label newcomer issues and invite EICrecon and GlueX developers to take ownership of specific components through PRs.

The top author wrote 90.9% of commits in 24 months, no merged PR in 12 months had a non-author reviewer, and one person merged all PRs.

Gaps to the next level

• One person writes over 80% of commits and nobody else reviews or merges.
• No CODEOWNERS or maintainer list.

Actions

• high S Add CODEOWNERS naming at least two maintainers and have a second maintainer review and merge PRs.

The LICENSE file lists authors and the docs describe the release procedure, but there is no documented decision process or path to maintainership; the only open milestone is past its due date.

Gaps to the next level

• No GOVERNANCE document or description of who decides and how to become a maintainer.

Actions

• medium S Add GOVERNANCE.md naming the maintainers, the decision process, the path to maintainership and the link to the ePIC software meetings where JANA2 changes are discussed.

The JeffersonLab organization Contributor Covenant applies with a reporting phone number, but neither the README nor the docs name a support channel; GitHub Discussions is enabled with only a welcome post and release announcements.

Gaps to the next level

• No support channel documented in the README or docs.

Actions

• medium S Add a "Getting help" section to README.md and docs/index.md linking GitHub Discussions (or the EIC Mattermost channel) and the issue tracker.

The eic-spack recipe provides the latest release 2026.03.01, which eic-shell ships; the recipe was updated one day after the release.

10 releases in 24 months, a documented CalVer scheme (YEAR.MAJOR.PATCH), and notes for every release. Releases are cut manually, there is no deprecation policy, and breaking changes are not consistently flagged with migration notes.

Gaps to the next level

• No release workflow; the release procedure is manual.
• No deprecation policy; breaking changes lack a consistent section and migration notes.

Actions

• medium M Add a tag-triggered .github/workflows/release.yml that creates the GitHub release, and add a "Breaking changes / Migration" section and a deprecation policy to docs/Download.md.

Dependencies are declared through find_package in CMakeLists.txt without minimum versions, and vendored code includes Catch2 2.13.7 (2021) and a 2002 md5 implementation.

Gaps to the next level

• No VERSION on find_package for podio, ROOT, cppzmq or Xerces-C.
• Vendored Catch2 v2 and md5 are no longer maintained upstream; no Dependabot or SECURITY.md.

Actions

• medium S Add minimum VERSION arguments to every find_package and use the Catch2 v3 package from eic-shell/Spack instead of src/external/catch2.

Containerfiles for development environments exist, but only the CUDA container is documented, CI images are unpinned (:latest, nightly), and configuration is only dumped on request rather than recorded with outputs.

Gaps to the next level

• No documented, versioned environment (eic-shell version or tagged image) per release.
• Parameter values and software versions are not recorded with outputs by default.

Actions

• medium S State in docs/Download.md the eic-shell release each JANA2 release is tested with, and document running in that image.

CI builds and tests on Linux (GCC, eic-shell) and macOS (AppleClang), with no site-specific paths in code, JANA2 runs unmodified in ePIC production campaigns through EICrecon, and CUDA support is provided through an example plugin and documented container.

JANA2 is itself the EIC-supported reconstruction framework and integrates podio for its data model; EICrecon and ejana in eic-spack depend on it.

JANA2 inserts and retrieves podio collections in podio::Frames and its examples read and write podio ROOT files; it does not declare or check a data-model version and has no I/O round-trip test.

Gaps to the next level

• No write-then-read round-trip test of podio files in ctest.
• Only compile-time podio version guards; no data-model version recorded or checked.

Actions

• medium S Add a ctest that writes a podio file with PodioFileWriter, reads it back with PodioFileReader and compares collection contents.

CI builds, tests and runs EICrecon in the eic_xl:nightly image, but neither the README nor the docs describe building or running JANA2 in eic-shell.

Gaps to the next level

• Building and running in eic-shell is not documented.
• CI tests only the nightly image, not a pinned stable eic-shell release.

Actions

• medium S Document in docs/install.md how to use the eic-shell JANA2 and how to build a development copy inside eic-shell.

eic-shell ships the latest JANA2 release with ROOT 6.40.04 and podio 1.8; ROOT 6.40 incompatibility (#500) was fixed the day it was reported and podio's removed operator-> was handled before removal (#477). The nightly eic-shell build shows deprecation warnings in JANA2 code only from pybind11 and the Python C API, not from EIC-supported components.

LICENSE carries a BSD-3-Clause-style text modified with "All Rights Reserved", "as a licensed user" and a U.S. Government clause, which GitHub does not recognize as an SPDX license.

Gaps to the next level

• No recognized SPDX identifier; the license text deviates from standard BSD-3-Clause.

Actions

• high S Replace LICENSE with the standard BSD-3-Clause text (keeping the government notice in a separate NOTICE file) so GitHub detects BSD-3-Clause.

CITATION.cff and a Zenodo concept DOI with a DOI for every release exist, but both name a single collective author and no contributor list is maintained.

Gaps to the next level

• No maintained author or contributor list; CITATION.cff and Zenodo list one collective author.

Actions

• medium S List the individual contributors in CITATION.cff (or .zenodo.json) and the ACAT 2019 paper as preferred-citation.

JANA2 ships in eic-shell, is the framework of EICrecon used in ePIC production campaigns, and is used by GlueX's halld_recon outside EIC.

The repository is owned by Jefferson Lab and the LICENSE states the software was developed under a U.S. Government contract by Jefferson Science Associates; there is no documented multi-institution maintenance commitment or succession plan.

Gaps to the next level

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

Actions

• medium S Document in the README the maintaining institutions, the owning ePIC/JLab software group, and the plan for maintainer turnover.