term-scope Debian packaging
===========================

This package is maintained with git-buildpackage (gbp) on the "debian"
branch; upstream development happens on "main" and releases are tagged
vX.Y.Z there.  See debian/gbp.conf.

Vendored Rust dependencies
--------------------------

Debian package builds are offline, and the crate dependencies are not
packaged in Debian 11-13, so the source package uses a 3.0 (quilt)
multi-tarball layout:

  term-scope_X.Y.Z.orig.tar.xz         upstream tree at tag vX.Y.Z
  term-scope_X.Y.Z.orig-vendor.tar.xz  `cargo vendor` output; unpacks
                                       to vendor/ in the source tree

debian/rules points cargo at vendor/ via a source-replacement config
and builds with --frozen, so the build never touches the network.

The tarballs are NOT stored in git (pristine-tar would add a ~26MB
blob per release).  debian/tarball-checksums records two sha256s per
tarball:

  *.tar     uncompressed content — reproducible on ANY machine
            (git archive from the tag, cargo vendor from the locked
            Cargo.lock, fixed tar order/ownership/mtime)
  *.tar.xz  the released compressed bytes — only reproducible with
            the same xz version (compressed output changes between
            Debian releases; xz >= 5.8 block-splits by default)

debian/scripts/vendor-tarball.sh generates the tarballs once per
release and records both sums; on later runs it verifies (regenerating
missing files first).  A content mismatch is a hard error.  A
compressed-bytes mismatch with matching content just means a different
compressor: fine for local builds, but never upload such a file for an
already-released version — fetch the released tarball instead
(apt-get source / origtargz, or copy it from the release area).
gbp finds the tarballs in the parent directory (tarball-dir in
debian/gbp.conf).

Cutting a release
-----------------

 1. Tag the release on main:        git tag vX.Y.Z main
 2. Merge it into this branch:      git checkout debian && git merge vX.Y.Z
 3. Generate the tarballs:          ./debian/scripts/vendor-tarball.sh
    (needs network access; writes both tarballs to the parent directory
    and records their sha256s in debian/tarball-checksums)
 4. Update the changelog:           gbp dch --new-version X.Y.Z-1
    then review, commit along with debian/tarball-checksums.
 5. Build:                          gbp buildpackage
 6. When satisfied:                 gbp tag

Rebuilding an already-released version (e.g. a -2 revision) reuses the
tarballs if still present, or regenerates them with the same script;
the .tar checksums guarantee the content matches what was originally
shipped even when a different xz version produces different .xz bytes.

Per-distribution rebuilds append the CDS-style suffix to the Debian
revision, e.g. 0.1.0-1+deb13.

Tests
-----

The package build runs the workspace unit tests.  The end-to-end test
(term_scope/tests/e2e_ioc.rs) spawns a live soft IOC and needs
python3-pcaspy; it is #[ignore]d and remains a developer-run check:

    cargo test -p term_scope -- --ignored
