# Sustainability action plan: ePIC geometry

From the EIC Software Sustainability Review, pass `2026-10-12`, assessed at commit `2e1d4f73eed9`. Full assessment: https://eic.github.io/SoftwareSustainabilityReview/projects/epic.html

Levels: 0 Absent · 1 Initial · 2 Established · 3 Sustained. Each item names the step to the next level.

## High priority

- [ ] Cache the `npsim-dis` HepMC3 input files with `actions/cache` (or retry the XRootD read) in `.github/workflows/linux-eic-shell.yml` so remote-server timeouts no longer fail main. *(`eng.ci`, now level 1, effort S)*
- [ ] Add `.github/CODEOWNERS` assigning two owners per `src/`/`compact/` subsystem directory. *(`com.bus-factor`, now level 1, effort S)*
- [ ] Document the monthly release and backport procedure in `RELEASING.md` and have a second maintainer publish a release. *(`com.bus-factor`, now level 1, effort S)*
- [ ] Add `CODE_OF_CONDUCT.md` (or link the ePIC collaboration code of conduct) with a reporting contact. *(`com.conduct`, now level 1, effort S)*

## Medium priority

- [ ] Add a clang-tidy job on changed `src/` files using the exported `compile_commands.json` from the eic-shell build. *(`eng.static-quality`, now level 2, effort S)*
- [ ] Add an "Installation" README section naming dependencies with minimum versions and the eic-shell route (`/opt/detector` builds and `source install/bin/thisepic.sh`), and link the EIC geometry-development tutorial. *(`doc.user`, now level 1, effort S)*
- [ ] Add a quick-start example running `npsim` on `epic_craterlake.xml` and a table of the configurations in `configurations/`. *(`doc.user`, now level 1, effort S)*
- [ ] Extend `.github/CONTRIBUTING.md` with eic-shell/devcontainer setup, the cmake build, and the `checkGeometry` and `scripts/checkOverlaps.py` commands CI runs. *(`doc.contributing`, now level 1, effort S)*
- [ ] Review the 58 open issues older than a year, close or label each with the existing `topic:` labels, and apply a topic label to every new issue. *(`com.responsiveness`, now level 1, effort S)*
- [ ] Link the 15 `good first issue` issues from the README and CONTRIBUTING.md and review fork PRs from non-members. *(`com.contributors`, now level 1, effort S)*
- [ ] Add `GOVERNANCE.md` naming the maintainers and core developers, the decision process, and the path to reviewer and maintainer. *(`com.governance`, now level 1, effort S)*
- [ ] State the YY.MM.patch CalVer scheme and the `backport` label policy in the README. *(`dist.releases`, now level 1, effort S)*
- [ ] Add minimum versions to `find_package(fmt ...)` and an explicit `find_package(ROOT ...)`, and to the entries in `requirements.txt`. *(`dist.dependencies`, now level 1, effort S)*
- [ ] Add the validating `eic_xl:<version>-stable` tag to each release's notes and run the PR checks on that pinned image as well as nightly. *(`dist.reproducibility`, now level 2, effort S)*
- [ ] Add an `ubuntu-24.04-arm` build-and-checkGeometry job in `linux-eic-shell.yml`. *(`dist.portability`, now level 2, effort S)*
- [ ] Move the stable build in `linux-eic-shell.yml` to the current `eic_xl:<release>-stable` and run `check-geometry-configs` and the overlap checks on it. *(`eic.environment`, now level 2, effort S)*
- [ ] Add `.zenodo.json` and `CITATION.cff` author lists covering significant contributors, and add the concept DOI to the README and `CITATION.cff`. *(`via.citation`, now level 1, effort S)*
- [ ] State in the README the ePIC working group responsible for the geometry and the maintainers' institutions. *(`via.support`, now level 1, effort S)*
- [ ] Add a gcov/Codecov job that runs the per-configuration `checkGeometry` loop on a coverage build and publishes plugin coverage. *(`eng.testing`, now level 2, effort M)*
- [ ] Add a scripted check (e.g. `scripts/subdetector_tests/`) that compares dumped constants or material scans against stored references and is required for PRs that change `src/` or `compact/`. *(`eng.testing`, now level 2, effort M)*
- [ ] Add `docs/architecture.md` describing plugins, compact files, the Jinja2 configuration templates and the FileLoader, and install an `epicConfig.cmake`. *(`eng.modularity`, now level 2, effort M)*
- [ ] Add a `Doxyfile` and a job in `linux-eic-shell.yml` that publishes the generated plugin reference with the existing GitHub Pages artifacts site. *(`doc.developer`, now level 1, effort M)*
- [ ] Add a CI step that loads the exported TGeo file with uproot or ROOT and compares volume counts and material budget with the DD4hep geometry. *(`eic.data-model`, now level 2, effort M)*

## Low priority

- [ ] State in `.github/CONTRIBUTING.md` that contributions are accepted under LGPL-3.0-or-later (inbound = outbound) or require DCO sign-off. *(`via.license`, now level 2, effort S)*