algorithms

9 of 10 first-parent commits came from PRs and 5 of 8 PRs merged in 12 months (6 bot-authored) were approved by a person other than the author; the metric counts only the one non-bot PR (#25), which was self-merged without review. The ruleset requiring one approval is bypassed by admins (#25, #28, #30 merged unapproved; b54ac87 pushed directly), and there is no CODEOWNERS.

Gaps to the next level

• Fewer than 90% of merged PRs are reviewed by someone other than the author; admins bypass the required-approval ruleset.
• No CODEOWNERS file.

Actions

• medium S Remove the admin bypass from the "Default" ruleset so every PR, including maintainer and Dependabot PRs, needs one approval.
• medium S Add .github/CODEOWNERS naming at least two reviewers for core/ and cmake/.

The GitHub workflow builds and installs in eic-shell for GCC and Clang on every PR, push, and nightly, and these builds are required status checks, but it runs no tests because none exist.

Gaps to the next level

• CI does not run any test suite (ctest is never invoked).
• The legacy .gitlab-ci.yml targets the retired eicweb Juggler pipeline and C++17, which the project no longer builds with.

Actions

• medium S Add a ctest --test-dir build --output-on-failure step to .github/workflows/linux-eic-shell.yml once unit tests exist.
• low S Delete the obsolete .gitlab-ci.yml.

There are no test files and testing is a commented-out TODO; core/src/dummy.cpp contains property and logger checks that are compiled into the library but never executed.

Gaps to the next level

• No unit tests for Property, LoggerMixin, ServiceSvc, AlgorithmSvc, RandomSvc, or GeoSvc.

Actions

• high M Move the checks in core/src/dummy.cpp into Catch2 unit tests under core/tests/ registered with ctest, and run them in CI.

.clang-format and .clang-tidy are present and CI builds with -Werror -Wall -Wextra, but neither formatting nor clang-tidy is checked on PRs (clang-tidy runs only in the stale GitLab pipeline and is off by default in CMake).

Gaps to the next level

• No formatter or linter is enforced on PRs.

Actions

• medium S Add .pre-commit-config.yaml with the clang-format hook and enable pre-commit.ci (or a clang-format check job).
• medium S Add a CI job that configures with -DENABLE_CLANG_TIDY=ON in eic-shell.

A C++20 CMake library with small headers, configuration through Property members, internals in detail/, install targets, and an exported algorithmsConfig.cmake consumed by EICrecon. The architecture description is a class summary in the README, and test scaffolding (dummy.cpp) is compiled into the installed library.

Gaps to the next level

• No architecture document explaining how a host framework provides services and drives algorithms.
• core/src/dummy.cpp (test code printing to stdout) is built into the shipped libalgocore.

Actions

• medium S Add docs/architecture.md describing the service lifecycle, AlgorithmSvc, and how EICrecon/JANA2 binds GeoSvc, RandomSvc, and LogSvc.
• low S Remove core/src/dummy.cpp from the library sources once its checks move to tests.

The README is a class summary with no installation, dependency, build, or usage instructions, and the homepage named in the eic-spack recipe (https://eic.github.io/algorithms) returns 404.

Gaps to the next level

• No install instructions, dependency list, or runnable example of writing an algorithm.

Actions

• high S Add README sections for using the eic-shell build, building from source with CMake (DD4hep, EDM4hep, EDM4eic, fmt, Microsoft GSL with versions), and a minimal Algorithm<Input<...>, Output<...>> example.

Public headers carry plain // comments describing classes and most methods, but no API reference is generated or published (the GitLab pages job references a nonexistent doc/Doxyfile), and there is no architecture overview beyond the README class summary.

Gaps to the next level

• No generated API documentation and no architecture overview.

Actions

• medium S Add a Doxyfile for core/include and convert header comments to Doxygen form.
• medium S Write docs/architecture.md covering services, properties, and the algorithm interface.

Only the eic organization PR and issue templates apply; there is no CONTRIBUTING file in the repository or the organization describing setup, build, tests, or conventions.

Gaps to the next level

• No CONTRIBUTING describing eic-shell setup, build, tests, and coding conventions.

Actions

• medium S Add CONTRIBUTING.md covering eic-shell setup, CMake build, running tests, clang-format, and the PR/review process.

No issues were opened in 12 months; the single open issue (#24, opened 2025-05-01) is older than one year with no response.

Gaps to the next level

• All open issues are older than one year and unanswered; no labels are used.

Actions

• medium S Respond to and resolve or label issue

One non-bot author made all commits in 24 months; other changes came from Dependabot and the Copilot coding agent.

Gaps to the next level

• At most one active human author in 24 months.

Actions

• high M Recruit a second developer (for example from the EICrecon maintainer group) to own a component such as RandomSvc or GeoSvc and land PRs.

The top author wrote 100% of non-bot commits in 24 months and made every release, but a second person approved PRs #26, #27, #29, #31, and #32.

Gaps to the next level

• Bus factor of 1; no CODEOWNERS or maintainer list in the repository.

Actions

• high S Add .github/CODEOWNERS with two maintainers and have the second maintainer author and merge changes.

Original authors are identifiable from copyright headers and LICENSE.spdx, and decisions are visible in PRs, but there is no documented decision process, maintainer path, or roadmap.

Gaps to the next level

• No documented governance (who decides, how to become a maintainer).

Actions

• medium S Add a "Maintainers and governance" README section naming the maintainers, the owning ePIC body, and how decisions are made.

The eic organization issue template links the ePIC Mattermost and weekly software meetings as support channels, but no code of conduct applies in the repository or organization.

Gaps to the next level

• No code of conduct with a reporting contact.

Actions

• high S Add CODE_OF_CONDUCT.md (or link the ePIC collaboration code of conduct) with a reporting contact, preferably in the eic/.github organization repository.

The eic-spack recipe provides the latest release 2.0.0 (added 2026-06-15, about one month after the 2026-05-12 release), and eic-shell ships 2.0.0.

Five releases in 24 months (at least two per year) have generated release notes, but no version scheme is documented and version_number still reads 1.0.0 at v2.0.0, so the installed library and CMake package report version 1.0.0.

Gaps to the next level

• No documented version scheme; the in-tree version is not updated at release.

Actions

• medium S State SemVer in the README and set version_number to the tag version in each release commit.

Dependencies are declared in CMake, but only EDM4hep has a minimum version, Microsoft GSL is found without REQUIRED yet linked unconditionally, EDM4hep/EDM4eic are linked but unused in the code, and the package config re-finds only fmt (and a removed Acts component). Dependabot covers GitHub Actions, but actions are not SHA-pinned and run-cvmfs-osg-eic-shell@main floats.

Gaps to the next level

• Minimum versions missing for DD4hep, EDM4eic, fmt, and Microsoft GSL; unused EDM4hep/EDM4eic dependencies remain.
• algorithmsConfig.cmake does not find_dependency the public link dependencies DD4hep, EDM4hep, EDM4eic, and GSL.

Actions

• medium S Add VERSION minimums to every find_package, make Microsoft.GSL REQUIRED, and drop EDM4hep/EDM4eic if unused.
• medium S Add find_dependency calls for all public link dependencies in cmake/algorithmsConfig.cmake.in and remove the Acts block.

The only environment specification is the unpinned eic_xl:nightly image in the CI workflow, and building or running in it is not documented; RandomSvc accepts a seed property.

Gaps to the next level

• No documented environment (eic-shell version) for development or releases.

Actions

• medium S Document in the README the eic-shell release each algorithms release was built and tested with.

CI builds with GCC and Clang on Linux x86_64 with no site-specific paths, but no tests run on either configuration, so the two-toolchain condition is met for builds only.

Gaps to the next level

• No tests run on the GCC and Clang builds.

Actions

• medium S Run the unit tests with ctest in both the g++ and clang++ matrix jobs.

The geometry service wraps DD4hep rather than reimplementing it, and the library is itself an EIC-supported component that EICrecon requires and builds its algorithms on.

The library performs no event I/O; its only data input is DD4hep compact XML loaded by GeoSvc in standalone mode, and it declares no data-model version check or round-trip test.

Gaps to the next level

• No declared or checked EDM4hep/EDM4eic version despite linking both.

Actions

• low S Either use EDM4eic types in the public interface with a checked minimum version, or remove the EDM dependencies and document that the library is data-model agnostic.

CI builds in the eic_xl:nightly image via eic/run-cvmfs-osg-eic-shell, but building or using the library in eic-shell is not documented and no pinned stable release is tested.

Gaps to the next level

• eic-shell usage is not documented; only the nightly image is tested.

Actions

• medium S Document the eic-shell build in the README and add a matrix entry for a pinned stable eic_xl release next to nightly.

The nightly eic-shell build passes without compiler deprecation warnings and eic-shell ships the latest release, but support for EDM4hep 1.0 (released 2026-01-20) landed only on 2026-04-07, and -Wno-error=deprecated-declarations keeps deprecations non-fatal.

Gaps to the next level

• Adaptation to the EDM4hep 1.0 release took about 11 weeks, longer than one eic-shell release cycle.

Actions

• low S Remove -Wno-error=deprecated-declarations so the nightly eic-shell job fails on deprecated APIs.

LGPL-3.0 is detected, LICENSE.spdx declares LGPL-3.0-or-later, and dependencies (DD4hep LGPL, EDM4hep Apache-2.0, fmt and GSL MIT) are compatible. Four source files lack SPDX headers, LICENSE.spdx names the package "Juggler", and no contribution terms are documented.

Gaps to the next level

• SPDX headers missing in random.h, detail/random.h, detail/upcast.h, and src/random.cpp; no inbound=outbound or DCO statement.

Actions

• low S Add SPDX headers to the four files, fix PackageName in LICENSE.spdx, and add the REUSE lint to CI.

There is no CITATION.cff, Zenodo metadata, DOI, or citation request.

Gaps to the next level

• No citation information of any kind.

Actions

• high S Add CITATION.cff with the author list and enable the Zenodo-GitHub integration for release DOIs.

EICrecon, the ePIC reconstruction framework, requires the library and builds its algorithms on it, and it ships in eic-shell.

The repository is in the eic organization and its authors are identifiable, but no owning ePIC body, institutional commitment, or funding is stated, and one person does all maintenance.

Gaps to the next level

• No stated maintenance responsibility within the EIC or ePIC structure.

Actions

• high S State in the README the ePIC working group that owns the library and the maintainers' institutions.