# Sustainability action plan: EDM4eic

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

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

## High priority

- [ ] Add `ctest --test-dir build --output-on-failure` to the `run:` block of the build-test step in `.github/workflows/linux-eic-shell.yml`. *(`eng.ci`, now level 1, effort S)*
- [ ] Run ctest in `linux-eic-shell.yml` (see eng.ci) so the existing round-trip test gates every PR. *(`eng.testing`, now level 1, effort S)*
- [ ] Add `.pre-commit-config.yaml` with clang-format for `utils/` and `test/` and a YAML linter for `edm4eic.yaml`, and enable pre-commit.ci. *(`eng.static-quality`, now level 0, effort S)*
- [ ] Add `-Wall -Wextra` to the `write_events`, `read_events` and generated datamodel targets. *(`eng.static-quality`, now level 0, effort S)*
- [ ] Add `CODE_OF_CONDUCT.md` (or link the ePIC collaboration code of conduct) with a reporting contact. *(`com.conduct`, now level 0, effort S)*
- [ ] Add a "Getting help" section to `README.md` linking the ePIC Mattermost channel for the data model. *(`com.conduct`, now level 0, effort S)*

## Medium priority

- [ ] Add unit tests for `utils/include/edm4eic/vector_utils.h` and `analysis_utils.h`. *(`eng.testing`, now level 1, effort S)*
- [ ] Add `find_dependency(podio 1.2)`, `find_dependency(EDM4HEP)` and `find_dependency(ROOT 6)` to `cmake/EDM4EICConfig.cmake.in`. *(`eng.modularity`, now level 2, effort S)*
- [ ] Add an "Installation" section to `README.md` naming podio, EDM4hep and ROOT with minimum versions and the `eic-shell` and `spack install edm4eic` routes. *(`doc.user`, now level 1, effort S)*
- [ ] Add a short C++ and uproot example reading an EDM4eic collection, linked from the README. *(`doc.user`, now level 1, effort S)*
- [ ] Add `CONTRIBUTING.md` covering eic-shell setup, build, `ctest`, naming and units conventions for new datatypes, and the version-bump rule. *(`doc.contributing`, now level 1, effort S)*
- [ ] Add `.github/ISSUE_TEMPLATE/` with "new datatype proposal" and "bug report" templates. *(`doc.contributing`, now level 1, effort S)*
- [ ] Close or label each of the 21 open issues older than one year, and label every new issue on arrival. *(`com.responsiveness`, now level 1, effort S)*
- [ ] Extend `.github/CODEOWNERS` to cover `CMakeLists.txt`, `utils/` and `test/` with two named maintainers each. *(`com.bus-factor`, now level 2, effort S)*
- [ ] Add `RELEASING.md` describing the version bump, tag, GitHub release and eic-spack update. *(`com.bus-factor`, now level 2, effort S)*
- [ ] Add `GOVERNANCE.md` stating that the ePIC admin team approves schema changes, how proposals are decided, and how one becomes a maintainer. *(`com.governance`, now level 1, effort S)*
- [ ] State in `README.md` which changes require a major, minor or patch bump, and follow it for schema-breaking changes. *(`dist.releases`, now level 1, effort S)*
- [ ] Remove the CLI11 lookup with the dead `event_merge` target and add `find_dependency` calls to `cmake/EDM4EICConfig.cmake.in`. *(`dist.dependencies`, now level 1, effort S)*
- [ ] Document in `README.md` the eic-shell release that first ships each EDM4eic version, and add a CI job pinned to the current stable eic-shell. *(`dist.reproducibility`, now level 1, effort S)*
- [ ] Add a matrix to build-test in `linux-eic-shell.yml` that also builds with `CXX=clang++` and on `ubuntu-24.04-arm`. *(`dist.portability`, now level 1, effort S)*
- [ ] Add an eic-shell section to `README.md` (EDM4eic is preinstalled; building a development version inside eic-shell). *(`eic.environment`, now level 1, effort S)*
- [ ] Add a matrix entry with `platform-release: eic_xl:<current stable>` to build-test in `linux-eic-shell.yml`. *(`eic.environment`, now level 1, effort S)*
- [ ] State in `README.md` the owning ePIC body, the maintainers' institutions and what happens when a maintainer leaves. *(`via.support`, now level 2, effort S)*
- [ ] Extend `test/write_events.h` and `test/read_events.h` to write and read back one object of every datatype and link type. *(`eng.testing`, now level 1, effort M)*
- [ ] Add `docs/conventions.md` covering units, covariance coordinate systems, parameter ordering and the association-to-link transition, and include it in the Doxygen input. *(`doc.developer`, now level 2, effort M)*
- [ ] Invite detector and analysis groups that propose datatypes in issues (for example *(`com.contributors`, now level 2, effort M)*
- [ ] Document, per datatype that has an EDM4hep counterpart, why the EDM4eic version is needed, or replace it with the EDM4hep type. *(`eic.reuse`, now level 1, effort M)*
- [ ] Deprecate and schedule removal of the MCReco*Association datatypes in favor of the link types. *(`eic.reuse`, now level 1, effort M)*
- [ ] Add a CI job that reads a stored file from the previous release with the PR build, using podio schema evolution. *(`eic.data-model`, now level 2, effort M)*
- [ ] Add `CITATION.cff` with the concept DOI and a DOI badge in `README.md`, and cite an EDM4eic description in an ePIC software publication. *(`via.citation`, now level 2, effort M)*

## Low priority

- [ ] Delete the unused `.gitlab-ci.yml`. *(`eng.ci`, now level 1, effort S)*
- [ ] Remove `utils/src/event_merge.cpp` and its CMake block, or port it to `podio::Frame`. *(`eng.modularity`, now level 2, effort S)*
- [ ] Correct `LICENSE.spdx` to describe EDM4eic, and add REUSE metadata recording the Apache-2.0 and MIT files. *(`via.license`, now level 2, effort S)*
- [ ] State inbound = outbound licensing in a `CONTRIBUTING.md`. *(`via.license`, now level 2, effort S)*