# Sustainability action plan: ai-epic-background

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

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

## High priority

- [ ] Enable a ruleset on `main` that requires a pull request with one approving review, and route all changes through PRs. *(`eng.change-control`, now level 1, effort S)*
- [ ] Add pytest tests in `tests/` for `concat_runs_with_unique_events` in `scripts/merge_reco_particles_to_feather.py` and the DID grouping in `scripts/summarize_rucio_dids.py`, using small fixture CSV and text files. *(`eng.testing`, now level 0, effort S)*
- [ ] Add `.pre-commit-config.yaml` with `ruff` and `ruff-format` hooks and enable pre-commit.ci on the repository. *(`eng.static-quality`, now level 0, effort S)*
- [ ] Rewrite the README layout and quick start for the current tree (`simulation-pipeline/`, `scripts/`, `analyses/`) and add an "Installation" section covering `uv sync` and eic-shell with versions. *(`doc.user`, now level 1, effort S)*
- [ ] Add `CODEOWNERS` naming two maintainers and have the second maintainer review every PR. *(`com.bus-factor`, now level 0, 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` with a reporting contact, or link the ePIC collaboration code of conduct from the README. *(`com.conduct`, now level 1, effort S)*
- [ ] Tag a first release (for example `v0.1.0`, matching `pyproject.toml`) with generated release notes, and state the version scheme in the README. *(`dist.releases`, now level 0, effort S)*
- [ ] Add `LICENSE` with the MIT text, set `license = "MIT"` in `pyproject.toml`, and ask the submodule owners to add a license. *(`via.license`, now level 1, effort S)*
- [ ] Add `CITATION.cff` listing the authors and enable the Zenodo–GitHub integration. *(`via.citation`, now level 0, effort S)*
- [ ] List the analyses and groups using the datasets in the README and link the docs site from the ePIC background working group pages. *(`via.adoption`, now level 0, effort S)*
- [ ] State the maintainers' institutions and the owning ePIC working group in the README. *(`via.support`, now level 0, effort S)*
- [ ] Recruit a co-developer from the ePIC background or AI/ML working group and route their changes through PRs. *(`com.contributors`, now level 0, effort M)*

## Medium priority

- [ ] Add `.github/workflows/test.yml` triggered on `pull_request` and `push` to `main` that runs `uv sync` and `uv run pytest`. *(`eng.ci`, now level 1, effort S)*
- [ ] Add `CONTRIBUTING.md` covering `uv sync`, running scripts in eic-shell, the submodule update procedure and the PR process. *(`doc.contributing`, now level 1, effort S)*
- [ ] Link the issue tracker from the docs site as the place to report dataset or script problems, and triage new issues with labels within a week. *(`com.responsiveness`, now level 1, effort S)*
- [ ] Add minimum versions to every dependency in `pyproject.toml`, drop unused ones, add `pyarrow`, and commit `uv.lock`. *(`dist.dependencies`, now level 1, effort S)*
- [ ] Pin every campaign config to a public `eic_xl` tag on CVMFS and commit `uv.lock` for the Python tools. *(`dist.reproducibility`, now level 1, effort S)*
- [ ] Run the test workflow on Python 3.12 and 3.13 (the eic-shell version) in a matrix. *(`dist.portability`, now level 1, effort S)*
- [ ] Document the column layout of every converter role in `docs/data-format.md`, including the EDM4eic version of the source files. *(`eic.data-model`, now level 1, effort S)*
- [ ] Add a CI job using `eic/run-cvmfs-osg-eic-shell` that runs the tests and `scripts/check_podio_files.py` on a small EDM4eic sample. *(`eic.environment`, now level 1, effort S)*
- [ ] Run the eic-shell CI job against `eic_xl:nightly` on a weekly schedule. *(`eic.currency`, now level 2, effort S)*
- [ ] Add a `[build-system]` table and move `scripts/*.py` into a package with `[project.scripts]` entry points. *(`eng.modularity`, now level 1, effort M)*
- [ ] Generate API pages for `scripts/` and `analyses/` (for example with `mkdocstrings` or `pdoc`) in the docs build in `.github/workflows/documentation.yml`. *(`doc.developer`, now level 1, effort M)*
- [ ] After packaging the scripts, publish the package to PyPI from a tag-triggered release workflow. *(`dist.packaging`, now level 1, effort M)*

## Low priority

- [ ] Add a `pull_request` trigger with a build-only job (no deploy) to `.github/workflows/documentation.yml`. *(`eng.ci`, now level 1, effort S)*
- [ ] Fix the submodule link in `docs/full-sim-pipeline.md` to the URL in `.gitmodules`. *(`doc.user`, now level 1, effort S)*
- [ ] Contribute the EDM4eic-to-CSV flattening as a benchmark or tool in an EIC repository such as `eic/detector_benchmarks`. *(`eic.reuse`, now level 2, effort M)*