# Sustainability action plan: afterburner

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

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

## High priority

- [ ] Add `.clang-format` and `.pre-commit-config.yaml` with clang-format and enable pre-commit.ci. *(`eng.static-quality`, now level 0, effort S)*
- [ ] Add `target_compile_options(... PRIVATE -Wall -Wextra -Wpedantic)` to the three targets in `cpp/*/CMakeLists.txt`. *(`eng.static-quality`, now level 0, effort S)*
- [ ] Respond to and label issues *(`com.responsiveness`, now level 0, effort S)*
- [ ] Add `.github/CODEOWNERS` naming at least two owners for `cpp/`. *(`com.bus-factor`, now level 1, effort S)*
- [ ] Add a "Maintainers" section to the README naming the maintainers, their roles and the owning ePIC working group. *(`com.governance`, now level 0, effort S)*
- [ ] Add `CODE_OF_CONDUCT.md` with a reporting contact, or link the ePIC collaboration code of conduct from the README. *(`com.conduct`, now level 1, effort S)*
- [ ] Add a `LICENSE` file with an OSI-approved license compatible with the bundled LGPL-2.1 gzstream code, agreed by the copyright holders. *(`via.license`, now level 0, effort S)*
- [ ] Add `CITATION.cff` listing the contributors and enable the Zenodo-GitHub integration. *(`via.citation`, now level 0, effort S)*

## Medium priority

- [ ] Add `push: branches: [main]` to the `on:` block of `.github/workflows/linux-eic-shell.yml`. *(`eng.ci`, now level 1, effort S)*
- [ ] Run `pytest python/test_abconv.py` with `TEST_ABCONV_EXE=install/bin/abconv` (and `ctest` once tests are registered) in the "Run test" step. *(`eng.ci`, now level 1, effort S)*
- [ ] Install the `afterburner` library and its headers with `install(TARGETS ... EXPORT)` and `install(DIRECTORY ...)`. *(`eng.modularity`, now level 1, effort S)*
- [ ] List every `find_package` dependency with minimum versions in the README "Installation" section and state that eic-shell provides them. *(`doc.user`, now level 1, effort S)*
- [ ] Add a README quick start that generates input with `python/gen_hepmc_event.py` and runs `abconv` on it. *(`doc.user`, now level 1, effort S)*
- [ ] Add a `Doxyfile` and a GitHub Pages workflow publishing the API docs for `cpp/afterburner/*.hh`. *(`doc.developer`, now level 1, effort S)*
- [ ] Add `docs/architecture.md` describing the library, converter and histogrammer and their data flow. *(`doc.developer`, now level 1, effort S)*
- [ ] Add `CONTRIBUTING.md` describing development in eic-shell, the CMake build, running the CI smoke test locally, and PR conventions. *(`doc.contributing`, now level 1, effort S)*
- [ ] Close or label the eight issues older than one year (#1, *(`com.responsiveness`, now level 0, effort S)*
- [ ] Review and merge or close external PRs *(`com.contributors`, now level 1, effort S)*
- [ ] State SemVer in the README and derive the `--version` string from `project(VERSION ...)` set to the release tag. *(`dist.releases`, now level 1, effort S)*
- [ ] Tag a release at least every six months with generated release notes. *(`dist.releases`, now level 1, effort S)*
- [ ] Add `VERSION` arguments to the `find_package` calls for HepMC3, yaml-cpp, CLHEP, GSL and ROOT. *(`dist.dependencies`, now level 1, effort S)*
- [ ] Replace `cpp/external/CLI` with `find_package(CLI11)` and drop the `json_struct` include path. *(`dist.dependencies`, now level 1, effort S)*
- [ ] Add a `--seed` option wired to `AfterburnerConfig::random_seed` and write the seed and abconv version into the GenRunInfo attributes. *(`dist.reproducibility`, now level 1, effort S)*
- [ ] Document in the README the eic-shell release that ships each afterburner release. *(`dist.reproducibility`, now level 1, effort S)*
- [ ] Add a CI matrix job building with Clang (`CXX=clang++` in eic-shell) or on `macos-latest` with Homebrew dependencies. *(`dist.portability`, now level 1, effort S)*
- [ ] Remove `ReaderGZ.h`, `gzstream.*` and the `gz` format path, and rely on `HepMC3::deduce_reader` with HepMC3 built with compression. *(`eic.reuse`, now level 1, effort S)*
- [ ] Add an attribute recording the afterburner version and attribute schema version, and a CI test that reads the output back with pyHepMC3 or uproot and checks the attributes. *(`eic.data-model`, now level 2, effort S)*
- [ ] Add a matrix over `platform-release` with a pinned `eic_xl:<release>` and `eic_xl:nightly` in `.github/workflows/linux-eic-shell.yml`. *(`eic.environment`, now level 2, effort S)*
- [ ] Drop the vendored `ReaderGZ.h` and CLI11 copies in favour of the HepMC3 and CLI11 versions shipped in eic-shell. *(`eic.currency`, now level 2, effort S)*
- [ ] State in the README the ePIC working group that owns afterburner and the maintainers' institutions. *(`via.support`, now level 1, effort S)*
- [ ] Add Catch2 unit tests under `cpp/tests/` for `Smearer` and `Afterburner::process_event` (crossing angle and vertex widths per preset) registered with `add_test`. *(`eng.testing`, now level 1, effort M)*
- [ ] Assert in CI that output vertex and angle distributions of the generated sample match expected crossing angle and widths within tolerance. *(`eng.testing`, now level 1, effort M)*
- [ ] Move the beam presets from `EicConfigurator.cc` into YAML files under `beam_configs/` loaded at run time (issue *(`eng.modularity`, now level 1, effort M)*