Week 12 -- Continuous integration and release

[moryev]

Purpose

Implement the original Week 12 — Continuous integration and release phase and complete Phase 7 — Portfolio-quality release.

This issue should turn the stabilized, documented toolkit into a reproducible release candidate with automated quality checks and a coherent public version.

Goal

A realistic v1.0.0 should not mean “perfect” or “feature-complete forever.” It should mean:

the public API, scientific assumptions, principal benchmarks, and main sensing demonstration are coherent, tested, documented, and reproducible.

If the project is not yet ready for that semantic commitment, choose the next appropriate pre-1.0 version instead; version choice should reflect API maturity, not ambition alone.

Continuous integration

Add GitHub Actions (or equivalent repository CI) to run the core quality gates automatically on pushes and pull requests.

At minimum:

• Install the package in a clean CI environment.
• Run pytest.
• Run linting.
• Run format checks.
• Run coverage reporting/checks where practical.
• Verify import/public-package smoke tests.

Keep CI deterministic and reasonably fast. Very expensive scientific benchmarks should not block every pull request unless a lightweight representative version is available.

Tooling

Preferred first-release tooling:

• Ruff for linting.
• Ruff formatting or Black for formatting; choose one canonical formatter.
• pytest for tests.
• pytest coverage tooling where useful.
• mypy only selectively if the package is ready for meaningful type checking; do not force noisy full-package typing merely to tick a box.

Document the chosen commands so local and CI validation use the same checks.

Repository configuration

• Add/update configuration in pyproject.toml for linting/formatting/testing where appropriate.
• Ensure CI uses the supported Python version(s).
• Decide whether to test one canonical Python version or a small supported-version matrix.
• Ensure generated/local artifacts are ignored appropriately.
• Verify package metadata is accurate.
• Verify dependencies and optional dependencies reflect actual runtime requirements.

Test/coverage review

• Run the complete test suite from a clean checkout/environment.
• Review coverage for scientifically important modules and public interfaces.
• Add tests for critical uncovered behavior where the gap represents real risk.
• Do not chase 100% coverage for trivial code at the expense of meaningful scientific tests.
• Confirm failure cases and validation behavior are covered, not only happy paths.

Release-readiness checks

• Week 11 README/quick-start instructions work from a clean environment.
• Main Week 10 sensing notebook runs with the documented setup.
• Representative benchmark/uncertainty workflows remain reproducible.
• Experimental-data example works with the committed/redistributable fixture or documented external-data path.
• SQLite example creates/queries a database successfully.
• Public imports are stable and intentional.
• No obvious roadmap-specific/private implementation names leak into the documented public API unless intentionally retained.
• Known limitations are documented.

Versioning and release

Choose the release version deliberately.

Potential outcomes:

v1.0.0
    public API is considered coherent/stable enough for the first mature release

or

next v0.x release
    substantial functionality is complete but API stability is not yet ready for 1.0

• Decide the release version.
• Update package version metadata consistently.
• Update CHANGELOG with a concise release summary.
• Verify CITATION.cff version/date metadata if applicable.
• Create a Git tag/release only after all release gates pass.
• Provide release notes highlighting major capabilities, scientific assumptions, and known limitations.

Release notes should summarize

• synthetic TCSPC simulation;
• classical reconvolution;
• ML benchmarking;
• robustness/generalization evaluation;
• uncertainty calibration/failure-awareness;
• experimental-data support;
• generalized/measured IRF handling;
• Bayesian inference if included;
• SQLite persistence/querying;
• Week 10 sensing demonstration;
• documentation/reproducibility improvements.

Optional packaging checks

If packaging/distribution is part of the release target:

• Build the package locally.
• Inspect build artifacts.
• Test installation from the built artifact in a clean environment.
• Decide whether PyPI publication is appropriate now or should be deferred.

PyPI publication is not required merely to call the repository release-ready; correctness and reproducibility come first.

Security / hygiene checks

• Confirm no credentials, private tokens, or local secrets are committed.
• Confirm no proprietary/restricted experimental files are included unintentionally.
• Confirm large generated artifacts are not accidentally tracked.
• Confirm license/citation information is consistent with distributed content.

Definition of first-release success

The original roadmap defined the minimal credible toolkit as being able to do six things well:

1. Simulate a mono-exponential TCSPC histogram with IRF convolution, background, and Poisson statistics.
2. Recover lifetime through classical reconvolution fitting.
3. Generate a controlled synthetic dataset.
4. Train at least one ML estimator and compare it against meaningful baselines.
5. Report errors across photon-count and noise conditions.
6. Demonstrate lifetime-based sensing in one reproducible notebook.

By Week 12, verify those six core capabilities still work cleanly despite the additional post-Week-9 features.

Explicitly out of scope for the first release

Do not delay release in order to add:

• a graphical desktop application;
• cloud deployment;
• deep neural networks;
• every possible decay model;
• GPU acceleration;
• arbitrary proprietary TCSPC file formats;
• real-time acquisition hardware;
• automatic publication-quality reporting;
• a general-purpose remote experiment-tracking platform.

Bayesian inference is included only because it is explicitly tracked and intentionally implemented before release; it should not trigger an open-ended expansion into every Bayesian model variant.

Acceptance criteria

• CI runs automatically on the intended repository events.
• Tests, linting, and formatting checks pass.
• Local validation commands match CI commands.
• Clean-install quick start succeeds.
• Week 10 sensing demonstration is reproducible.
• Major scientific assumptions and limitations are documented.
• Release version is chosen intentionally and applied consistently.
• CHANGELOG and citation metadata are updated.
• Release/tag is created only after all required checks pass.
• The repository presents a coherent portfolio-quality scientific software project.

Timing

Implement after Week 11 documentation/UX is complete.

#14 Week 11 documentation / UX
    ↓
#15 Week 12 CI / release
    ↓
portfolio-quality release