G4OCCT

97.1% of first-parent commits arrive through PRs and a ruleset requires PRs and eight status checks, but only 0.8% of merged PRs have a review from someone other than the author (the ruleset requires 0 approvals; reviews come from the Copilot bot or the author).

Gaps to the next level

• Fewer than 50% of merged PRs are reviewed by someone other than the author.
• The "Default" ruleset sets required_approving_review_count to 0 and lets the admin role bypass it always.
• No CODEOWNERS file.

Actions

• high M Recruit a second human reviewer and set required_approving_review_count to 1 in the "Default" ruleset.
• medium S Add .github/CODEOWNERS naming at least two reviewers for src/, include/ and src/dd4hep/.

ci.yml runs on every PR and push to main, builds in eic_xl with -Werror, runs ctest, the B1/B4c examples and DD4hep plugin tests, and eight jobs are required checks; 84% of default-branch runs succeeded and the latest two main runs fail (ASan leak reports in TGeoOCCTSolid tests).

Gaps to the next level

• Default-branch success rate is below 90%; main is red since 2026-09-14 (3 ASan test failures) and TGeoOCCTSolid.RootDrawingSmoke also failed on main in August.
• CI tests only the eic_xl nightly stack, not the declared minimum versions (Geant4 11.3, OCCT 7.8).
• The admin role can bypass the required status checks.

Actions

• medium S Fix or quarantine the failing TGeoOCCTSolid.* tests under ASan so main passes, and add a schedule: trigger to ci.yml to detect nightly-stack breakage.
• medium M Add a CI job building and testing against Geant4 11.3 and OCCT 7.8 (e.g. from .github/spack.yaml with pinned versions).

gtest unit tests cover each library class, per-fixture CTest tests compare OCCT navigation results against native Geant4 solids and recorded volume expectations, DD4hep plugin and example runs act as integration tests, coverage is published, and 47.5% of merged PRs touch tests.

pre-commit.ci runs clang-format, cmake-lint, codespell and markdownlint on every PR, IWYU fails PRs that need include changes, sanitizers are required checks, and CI builds with -Wall -Werror; clang-tidy runs but its result is discarded with || true.

Gaps to the next level

• clang-tidy findings never fail CI (|| true) and are not tracked to zero.
• LSan suppresses all OCCT allocations (leak:Standard::Allocate, leak:NCollection_IncAllocator::Allocate).

Actions

• medium S Remove || true from the clang-tidy-diff step in ci.yml so new clang-tidy findings on changed lines fail the PR.
• low M Replace the allocator-wide LSan suppressions with caller-scoped entries or explicit cleanup at test teardown.

A C++20 CMake library with public headers in include/G4OCCT/, internal kernel headers in src/, an exported G4OCCT::G4OCCT package config, a separately installed DD4hep plugin, XML-based material and sensitive-detector maps, and documented architecture; the largest file has 1273 lines.

The README gives build, install and downstream CMake usage, and B1/B4c/DD4hep examples are documented and run in CI, but the requirements table omits ROOT, DD4hep, yaml-cpp, GoogleTest and Google Benchmark, and there is no eic-shell, Spack or container install route.

Gaps to the next level

• Optional and test dependencies (ROOT, DD4hep, yaml-cpp 0.8, GoogleTest, Google Benchmark) are not listed with versions.
• No instructions for using G4OCCT from eic-shell, spack install g4occt or the ghcr.io/eic/g4occt image.
• No troubleshooting or FAQ material.

Actions

• medium S Extend the README Requirements table with ROOT, DD4hep, yaml-cpp and test dependencies, and add an "Installation" section covering eic-shell, eic-spack and ghcr.io/eic/g4occt.

Most public headers carry Doxygen comments, CI builds the Doxygen reference and deploys it to GitHub Pages from main, and design docs cover the solid-navigation mapping, kernel and optimizations; the design docs cite no external references and TGeoOCCTSolid overrides are undocumented.

Gaps to the next level

• Algorithm documentation (ray parity, BVH, inscribed-sphere prefilter) cites no literature or OCCT/Geant4 reference documents.
• The ~40 TGeoOCCTSolid override declarations have no Doxygen comments.

Actions

• low S Add a References section to docs/solid_navigation.md and docs/low_level_optimization.md citing the algorithms and OCCT/Geant4 documentation used.

AGENTS.md documents build requirements, testing rules, CI, code style and pre-commit, and org-level issue and PR templates apply, but there is no description of the PR process (branching, review, merge) or of setting up a development environment in eic-shell.

Gaps to the next level

• No CONTRIBUTING file or section describing how to open, review and merge a PR.
• No documented developer environment setup (eic-shell or devcontainer).

Actions

• medium S Add CONTRIBUTING.md covering eic-shell setup, the cmake/ctest commands, pre-commit, and the PR and review process, linking to AGENTS.md for conventions.

Median first response is 2.85 days, 87% of the 23 issues opened in 12 months were answered and 20 were closed (most through linked PRs), and the one external PR (#368) was reviewed; only 13% are labeled and most issues are filed by the maintainer.

Gaps to the next level

• Median first response exceeds 2 days.
• No documented triage process; 13% of issues labeled and no milestones.

Actions

• low S Label every new issue (bug/enhancement/question) and document the triage practice in CONTRIBUTING.md.

Two non-bot authors committed in 24 months from one e-mail domain; the second author contributed one PR.

Gaps to the next level

• Fewer than 4 active authors and fewer than 2 institutions in 24 months.

Actions

• high M Present G4OCCT at an ePIC simulation/geometry meeting and recruit co-developers from the groups adopting STEP geometry (e.g. the HCAL pilot in eic/epic#1140).

The top author wrote 99.2% of non-bot commits in 24 months and is the only human reviewer, merger, release author and listed eic-spack maintainer.

Gaps to the next level

• No second person reviews, merges or releases.
• No CODEOWNERS or maintainer list.

Actions

• high M Name a second maintainer with merge rights, add both to .github/CODEOWNERS and the eic-spack maintainers(...), and have that person review PRs.

The maintainer is identifiable from the eic-spack recipe and merge history, decisions are made in public PRs and recorded in AGENTS.md, and docs/goals.md has a roadmap, but there is no documented decision process, maintainer path or maintainer list in the repository.

Gaps to the next level

• No document stating who decides, how decisions are made, or how to become a reviewer or maintainer.
• Roadmap milestone numbers (v0.4–v1.0) do not match released versions (latest v0.3.0), and no GitHub milestones exist.

Actions

• medium S Add GOVERNANCE.md (or a README section) naming the maintainers, the decision process, and the path to reviewer/maintainer.

The eic org default issue-template config links the EPIC Mattermost for questions, but no code of conduct applies at repository or organization level.

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, and a "Getting help" README section pointing to Mattermost.

The eic-spack recipe provides 0.3.0 (added 10 days after release), and eic-shell ships g4occt, but at git.v0.2.1; 0.3.0 has not been picked up in the 26.08–26.10 eic-shell releases.

Gaps to the next level

• eic-shell still pins 0.2.1, more than one eic-shell release cycle after the 0.3.0 release.
• The eic-spack +dd4hep variant (required by eic-shell) does not set BUILD_ROOT_TGEO_SUPPORT, which 0.3.0 requires with BUILD_DD4HEP_PLUGIN.

Actions

• medium S Add BUILD_ROOT_TGEO_SUPPORT=ON (and a root dependency) for +dd4hep in the eic-spack recipe, then bump the eic/containers pin to 0.3.0.

Four SemVer releases since the March 2026 start, each with generated release notes, and the version scheme is documented in AGENTS.md; there is no changelog, deprecation policy or release workflow, and the tag/CMake version check failed for every tag.

Gaps to the next level

• No CHANGELOG flagging breaking changes or migration notes.
• No deprecation policy and no automated release workflow; project(VERSION) is 0.2.1 at tag v0.3.0 and the version check failed for v0.2.0, v0.2.1 and v0.3.0.

Actions

• medium S Add a release workflow that bumps project(VERSION), tags, and creates the GitHub release with a "Breaking changes" section, and add CHANGELOG.md.

Geant4 (11.3) and yaml-cpp (0.8) have minimum versions and test frameworks are fetched by hash, but find_package(OpenCASCADE), ROOT and DD4hep have no version constraint despite AGENTS.md stating OCCT 7.8.

Gaps to the next level

• find_package(OpenCASCADE), find_package(ROOT ...), find_package(DD4hep) and the find_dependency calls in G4OCCTConfig.cmake.in have no minimum version.
• Two vendored Geant4 RayTracer headers in src/tests/geometry/geant4_private/ record no Geant4 version.
• No SECURITY.md; enarx/spdx@master is unpinned; CI does not test minimum dependency versions.

Actions

• high S Add 7.8 to find_package(OpenCASCADE ...) and minimum versions for ROOT and DD4hep, and mirror them in G4OCCTConfig.cmake.in.

A Spack environment and Dockerfile define the build environment and container images are pushed to ghcr.io/eic/g4occt with SemVer tags, but using them is not documented and CI runs in the unpinned eic_xl nightly rather than that image.

Gaps to the next level

• No documentation of running G4OCCT in the published container or a pinned eic-shell version.
• The g4occt application's CSV outputs record no software versions or configuration.

Actions

• medium S Document docker run ghcr.io/eic/g4occt:<version> and the eic-shell release each G4OCCT release was tested with in the README.

Tests run only on x86_64 Linux with the eic_xl default compiler; the container workflow compiles for arm64 but with BUILD_TESTING=OFF.

Gaps to the next level

• No test run with a second compiler (Clang) or a second architecture (aarch64) or OS.

Actions

• medium S Add a Clang build-and-ctest job in eic_xl (CXX=clang++) and an ubuntu-24.04-arm ctest job.

G4OCCT builds on Geant4, DD4hep (detector-element plugins, DDG4 handoff) and ROOT TGeo and implements only CAD/BRep navigation, which no EIC component provides; the custom DDG4 geometry construction is justified in the docs. No other EIC repository uses its components yet and no upstream contributions were found.

Gaps to the next level

• No EIC software reuses the G4OCCT DD4hep plugins (eic/epic#1140 is open).

Actions

• medium M Land the HCAL pilot in eic/epic#1140 (or another epic subsystem) using G4OCCT_STEPSolid.

Inputs are STEP (ISO 10303) files and DD4hep compact XML, step2dd4hep writes DD4hep compact XML, and the material- and sensitive-detector-map XML formats are documented; map formats carry no version and there are no round-trip tests.

Gaps to the next level

• Material-map and SD-map XML have no declared or checked format version.
• No round-trip test (STEP → step2dd4hep compact → DD4hep load → compare volumes).

Actions

• low S Add a ctest that runs step2dd4hep on a fixture, loads the generated compact with DD4hep, and compares volumes with the fixture expectations.

Every CI job builds and tests inside eic_xl:nightly via eic/run-cvmfs-osg-eic-shell, but building or using G4OCCT in eic-shell is not documented for users (only a CI design snippet in docs/dd4hep_plugin.md).

Gaps to the next level

• README and docs do not describe building or running G4OCCT in eic-shell.
• CI tests only eic_xl:nightly, not a pinned stable eic-shell release.

Actions

• medium S Add an "Using G4OCCT in eic-shell" README section (prebuilt package and from-source build).

The build with -Werror and the functional tests pass against the current nightly (Geant4 11.4.1, OpenCASCADE 8.0, ROOT 6.40.04), but ASan leak failures in TGeoOCCTSolid tests appeared on main after OpenCASCADE 8.0 entered the stack and have been unresolved since 2026-09-14.

Gaps to the next level

• Sanitizer failures against the current nightly stack are not fixed within the eic-shell cycle.

Actions

• medium S Resolve the LeakSanitizer reports in TGeoOCCTSolid.MeshHooksProduceDrawableMesh, RootDrawingSmoke and TGeoOCCTSolidDD4hepEval.WrapsAsDD4hepSolid under the current nightly.

GitHub detects LGPL-2.1, the project declares LGPL-2.1-or-later in LICENSE.spdx and the container label, and SPDX headers are enforced in CI; contribution terms are not documented and LICENSE.spdx does not list the Geant4-licensed example and test files.

Gaps to the next level

• No documented contribution terms (inbound = outbound or DCO).
• Third-party Geant4 code (examples B1/B4c, geant4_private/ headers) is not recorded in LICENSE.spdx, which still states version 0.1.0.

Actions

• low S Add an inbound=outbound statement to CONTRIBUTING.md and list the Geant4-licensed paths in LICENSE.spdx (or adopt REUSE with REUSE.toml).

No CITATION.cff, Zenodo metadata, DOI, author list or citation request exists.

Gaps to the next level

• No machine-readable citation metadata or DOI.
• No author or contributor list.

Actions

• high S Add CITATION.cff with the authors and enable the Zenodo–GitHub integration for release DOIs.

G4OCCT ships in eic-shell, and one contributor outside the main author reported and fixed a units issue in the DD4hep path, but no EIC repository depends on it and the epic HCAL pilot (eic/epic#1140) is unmerged.

Gaps to the next level

• Not a dependency of any other EIC repository and not used in benchmarks or simulation campaigns.

Actions

• medium M Merge a G4OCCT-based geometry path in eic/epic or add a detector_benchmarks job comparing a STEP-backed subsystem with its GDML/CSG version.

The single maintainer is identifiable (eic-spack maintainer, release author) with a public university affiliation, and the repository is in the eic organization, but no working group ownership, funding or institutional commitment is stated.

Gaps to the next level

• No owning EIC/ePIC working group or funding acknowledgement in the README or docs.

Actions

• high S State the responsible ePIC working group and the maintainers' institutions and funding in the README.