# top level plan
Build the tui monitoring application

 * Generate specifications
 * Generate the plan

Crate-level plans:
 * term_scope/plan.md - implementation phases for the main application

# Debian packaging

Maintained on the `debian` branch with git-buildpackage (gbp); targets
Debian 11–13 built against the LIGO CDS repositories (epics-dev 7.x,
rustc/cargo >= 1.94.1 backports, libclang-19-dev).

## Decisions

 * Source and binary package name: `term-scope` (Debian forbids `_` in
   package names); the installed binary stays `/usr/bin/term_scope`.
 * Source format 3.0 (quilt) with a multi-tarball layout:
   * `term-scope_X.Y.Z.orig.tar.gz` — generated from the `vX.Y.Z` git tag.
   * `term-scope_X.Y.Z.orig-vendor.tar.xz` — output of `cargo vendor`
     (all locked crate dependencies), regenerated per release by
     `debian/scripts/vendor-tarball.sh`.  Debian builds are offline, and
     Debian 11–13 do not carry our crate set, so the dependencies must
     travel with the source package.
   * The tarballs are NOT stored in git: pristine-tar would add a
     ~26MB blob per release.  Both tarballs are deterministic (git
     archive from the tag, cargo vendor from the locked Cargo.lock,
     fixed tar order/ownership/mtime), so the script regenerates them
     on demand and verifies them against the sha256s committed in
     `debian/tarball-checksums`.  gbp picks them up from the parent
     directory (`tarball-dir`).
 * `debian/rules` is plain dh with cargo overrides (dh-cargo is built
   for archive-style librust packaging and fights vendored workspaces).
   The build points cargo at the vendor tree and runs `--frozen --release`.
 * `dh_auto_test` runs the workspace unit tests only.  The live-IOC e2e
   test stays a developer-run check, so python3-pcaspy is NOT a
   build-dependency (it is still needed to run the e2e test by hand).
 * Runtime dependency on libepics7.0.9 comes automatically from
   `${shlibs:Depends}`; the CDS packages ship the shared libraries in
   the standard multiarch path, so no rpath handling is needed.
 * Per-distro rebuilds follow the CDS `+debNN` version-suffix convention
   (e.g. `0.1.0-1+deb13`).

## Release workflow

 1. Tag `vX.Y.Z` on main.
 2. `git checkout debian && git merge vX.Y.Z`
 3. `./debian/scripts/vendor-tarball.sh` — generates both orig
    tarballs in the parent directory and records their sha256s in
    `debian/tarball-checksums`.
 4. Update `debian/changelog` (`gbp dch --new-version X.Y.Z-1`), commit
    along with `debian/tarball-checksums`.
 5. `gbp buildpackage` and, when satisfied, `gbp tag`.

## Phases

 1. [done when this lands] Bootstrap the `debian` branch: debian/control,
    rules, changelog, copyright (GPL-3+ with the LIGO M1500244 additional
    terms), gbp.conf, source/format, README.source, vendor-tarball script.
 2. Local build verification on Debian 13 (gbp buildpackage, lintian).
 3. Clean-chroot builds for Debian 11/12/13 with the CDS repos
    (sbuild or podman) — future work.
 4. Polish: man page (clap_mangen), bash completion, lintian cleanup —
    future work.

