# Sustainability action plan: TimeframeBuilder

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

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

## High priority

- [ ] Set the `main` ruleset to require one approving review and have a second person review every PR. *(`eng.change-control`, now level 1, effort S)*
- [ ] Add `.clang-format` and `.pre-commit-config.yaml` with clang-format, enable pre-commit.ci, and add `-Wall -Wextra` to `CMakeLists.txt`. *(`eng.static-quality`, now level 0, effort S)*
- [ ] Add `CONTRIBUTING.md` covering eic-shell setup, `make.sh`, running the CI chain locally, coding conventions and PR review. *(`doc.contributing`, now level 1, effort S)*
- [ ] Respond to and label every open issue, closing or scheduling the five older than one year. *(`com.responsiveness`, now level 0, effort S)*
- [ ] Add `CODEOWNERS` naming two maintainers and have the second maintainer author and review changes to `src/`. *(`com.bus-factor`, now level 1, effort S)*
- [ ] Add a "Maintainers" section to the README naming the maintainers and the owning ePIC working group. *(`com.governance`, now level 0, effort S)*
- [ ] Add `CODE_OF_CONDUCT.md` linking the ePIC collaboration code of conduct and its reporting contact. *(`com.conduct`, now level 1, effort S)*
- [ ] Add a `LICENSE` file with an OSI-approved license and declare it in the eic-spack recipe. *(`via.license`, now level 0, effort S)*
- [ ] Add `CITATION.cff` with the authors and enable the Zenodo-GitHub integration. *(`via.citation`, now level 0, effort S)*
- [ ] Add Catch2 unit tests for `DataSource::UpdateTimeOffset`, `CommandLineParser` and EDM4hep reference remapping, registered with `ctest`. *(`eng.testing`, now level 1, effort M)*
- [ ] Recruit a co-developer from another ePIC institution through the ePIC simulation/background working group and merge their PRs. *(`com.contributors`, now level 1, effort M)*

## Medium priority

- [ ] Add a `ctest` step to the build job in `linux-eic-shell.yml` once unit tests exist (see eng.testing). *(`eng.ci`, now level 1, effort S)*
- [ ] Add an "Installation" section covering the preinstalled `timeframe_builder` in eic-shell and from-source builds with minimum podio, EDM4hep, HepMC3, ROOT and yaml-cpp versions; fix `build.sh` to `make.sh`. *(`doc.user`, now level 1, effort S)*
- [ ] Add a quick-start that runs `configs/config_ci.yml` on the XRootD sample files used in CI. *(`doc.user`, now level 1, effort S)*
- [ ] Add a Doxyfile and a job that publishes the API docs next to the existing GitHub Pages reports, and update the README architecture section to the DataSource/DataHandler design. *(`doc.developer`, now level 1, effort S)*
- [ ] State SemVer in the README and publish a GitHub release with generated notes for every tag. *(`dist.releases`, now level 1, effort S)*
- [ ] Add minimum `VERSION` arguments to every `find_package` in `CMakeLists.txt` matching the current eic-shell versions. *(`dist.dependencies`, now level 1, effort S)*
- [ ] Document running in a named eic-shell release in the README and write the seed and configuration into the EDM4hep output's podio metadata. *(`dist.reproducibility`, now level 1, effort S)*
- [ ] Add a job to `linux-eic-shell.yml` that builds with `CXX=clang++` in eic-shell. *(`dist.portability`, now level 1, effort S)*
- [ ] Document in the README how the HepMC3 mode relates to HEPMC_Merger and when each should be used. *(`eic.reuse`, now level 1, effort S)*
- [ ] Add an eic-shell section to the README covering the preinstalled `timeframe_builder` and building from source inside eic-shell. *(`eic.environment`, now level 1, effort S)*
- [ ] State the owning ePIC working group and maintainer institutions in the README. *(`via.support`, now level 1, effort S)*
- [ ] Make the capybara job fail when the HepMC3-first and EDM4hep-first EICrecon outputs differ beyond a tolerance. *(`eng.ci`, now level 1, effort M)*
- [ ] Build the sources into a `timeframebuilder` library with installed headers and `install(EXPORT ...)` package config, and remove `link_directories(/opt/local/lib)`. *(`eng.modularity`, now level 2, effort M)*
- [ ] Implement the EDM4hep backend with `podio::ROOTReader`/`ROOTWriter` frames (issue *(`eic.reuse`, now level 1, effort M)*
- [ ] Check the input `podio_metadata` EDM4hep version against the linked EDM4hep and add a round-trip test reading merged output with uproot. *(`eic.data-model`, now level 2, effort M)*
- [ ] Replace hard-coded podio branch names (`_MCParticles_daughters`, `GPIntValues`) with podio API calls so podio layout changes do not break merging. *(`eic.currency`, now level 2, effort M)*