sjasmplus for Debian -- Source Package Documentation
----------------------------------------------------

Source format is "3.0 (quilt)". The Debian orig tarball is NOT a plain archive
of the upstream Git tree: it is DFSG-pruned and has the Git submodule contents
expanded into ordinary files. The Debian-facing Git history therefore tracks
imported, repacked `+dfsg` tarballs rather than upstream commits directly.

Terminology: `upstreamvcs` = the original sjasmplus repository (real upstream
development, submodules, tags like `v1.23.1`). `upstream/*` and `debian/*` are
the Debian-side branches in the Salsa packaging repository.

1. REPOSITORY MODEL
===================
Two repositories, kept as separate local clones (see section 7):

* upstreamvcs repository (GitHub)
  - `master`: upstream development; release tags `v1.23.1`; real submodules
  - `gen-dfsg-tarball`: helper branch carrying `debian/` metadata on top of an
    upstream release, used only to generate the canonical `+dfsg` orig tarball

* Salsa packaging repository
  - `upstream/latest`: imported, pruned `+dfsg` source (submodules flattened to
    plain files); the canonical archived form of the orig tarball
  - `pristine-tar`: binary delta that reproduces the exact upstreamvcs `+dfsg` tarball
  - `debian/latest`: packaging branch, descends from `upstream/latest`, adds the
    `debian/` directory
  - upstreamvcs `master` and other branches/tags are never pushed here

2. DESIGN PRINCIPLES
====================
Why repacking is needed:

* DFSG: embedded ROM assets under `tests/integration/` are excluded
* convenience copies and generated files are removed per `debian/copyright`
* submodule contents are flattened into normal files (avoids gitlinks and the
  extra unused files a full submodule checkout would pull in)

Key decisions, all intentional:

* `debian/copyright` `Files-Excluded` is the single source of truth for every
  exclusion; `mk-origtargz` reads it directly when building the `+dfsg` tarball.

* The orig tarball must stay byte-stable: the `.dsc` records its hash and later
  Debian revisions reuse the same orig. The `+dfsg` tarball is generated once
  (expanding submodules), published on the GitHub release, imported into
  `upstream/latest`, and committed to `pristine-tar`. `gbp` and Salsa CI then
  reproduce that exact file from `pristine-tar`, so the archive copy stays
  identical to the published one.

* `debian/watch` is for upstream version monitoring only, NOT orig generation:
  uscan / `mk-origtargz` on a plain GitHub archive cannot expand the submodule
  contents (e.g. `LuaBridge/LuaBridge.h`) the build needs. The manual generation
  step is deliberate and is currently the only path producing a build-complete,
  DFSG-pruned tree.

3. PER-RELEASE WORKFLOW
=======================
Assumes the Salsa repository already exists (first-time setup: section 8).
Replace `1.23.1` with the release being packaged.

Step 1 - generate the `+dfsg` tarball. In the upstreamvcs clone, on
`gen-dfsg-tarball`, with `debian/changelog` set to the target version:

  gbp export-orig --upstream-tree=v1.23.1 --submodules --tarball-dir=..
  mk-origtargz --repack --compression xz ../sjasmplus_*.orig.tar.gz
  rm ../sjasmplus_*.orig.tar.gz

Yields `../sjasmplus_1.23.1+dfsg.orig.tar.xz`. `gbp export-orig` needs the
`debian/` metadata and `mk-origtargz` needs `debian/copyright`, hence the helper
branch. Publish this file on the upstream GitHub release.

Step 2 - import into Salsa. In the Salsa clone, on `debian/latest`:

  gbp import-orig --no-symlink-orig \
    --debian-branch=debian/latest --upstream-branch=upstream/latest \
    ../sjasmplus_1.23.1+dfsg.orig.tar.xz
  # merges upstream/latest into debian/latest; merge manually if it does not

`gbp.conf` has `pristine-tar = True`, so import also records the pristine-tar
delta and creates the upstream tag `upstream/1.23.1+dfsg`.

Step 3 - adjust packaging, update the changelog (section 4), then build:

  gbp buildpackage -us -uc        # source + binary; --git-ignore-new if needed
  lintian -EviIL +pedantic ../sjasmplus_*.changes
  wrap-and-sort -vast             # normalize debian/* formatting if changed

Step 4 - finalize and tag (UNTESTED end-to-end; confirm with sponsor):

  gbp dch --release --commit      # UNRELEASED -> unstable, drop ~snapshot
  gbp buildpackage -us -uc -S     # source-only upload build
  lintian -EviIL +pedantic ../sjasmplus_*.changes
  gbp tag                         # creates debian/1.23.1+dfsg-1

Step 5 - push everything. A plain branch push does NOT send tags (in git-cola
tick "push tags", or push them by name):

  git push origin upstream/latest
  git push origin pristine-tar
  git push origin debian/latest
  git push origin tag upstream/1.23.1+dfsg
  git push origin tag debian/1.23.1+dfsg-1

Step 6 - upload (sponsored). Only sign/dput once the sponsor approves:

  debsign ../sjasmplus_*_source.changes -k<maintainer@email>
  dput mentors ../sjasmplus_*_source.changes   # or the sponsor's target

Optionally open the next cycle to avoid accidental version reuse:

  gbp dch --snapshot && git commit -m "debian: open next snapshot" debian/changelog

4. CHANGELOG MAINTENANCE WITH dch
=================================
`dch` (devscripts) edits `debian/changelog`; `gbp dch` wraps it to harvest Git
commit messages into entries. Common uses:

  gbp dch                collect new commits into the topmost entry
  gbp dch --snapshot     append a `~`-suffixed snapshot entry (UNRELEASED, WIP)
  gbp dch --release      finalize: drop `~`, set distribution, ready to upload
  dch -i                 new entry, bump Debian revision (-1 -> -2)
  dch -v <version>       new entry at an explicit version
  dch -r                 release current entry (set distribution + timestamp)
  dch -e                 just open the changelog in the editor

For an upload the entry must target a real distribution (e.g. `unstable`), not
`UNRELEASED`, which marks work-in-progress and blocks upload tooling.

5. CONTAINERIZED PACKAGING (PODMAN)
===================================
The host need not be Debian sid; the packaging workflow can run in an isolated
Debian Unstable container.

  # Create and run the isolated workspace
  podman run --interactive --tty --env='DEB*' --name deb-pkg-env \
    --shm-size=1G --cap-add SYS_PTRACE --volume=$PWD:/tmp/test:Z \
    --workdir=/tmp/test debian:sid bash

  # Relaunch after exit (-ai = attach + interactive)
  podman start -ai deb-pkg-env

  # Inject identity variables
  echo 'export DEBFULLNAME="Peter Helcmanovsky"' >> ~/.bashrc
  echo 'export DEBEMAIL="ped@7gods.org"' >> ~/.bashrc
  source ~/.bashrc

  # Install maintainer tooling, then resolve build-deps from debian/control:
  #   git git-buildpackage pristine-tar  - DEP-14 VCS workflow (gbp, pristine-tar)
  #   devscripts                         - dch, debsign, mk-build-deps, uscan,
  #                                        mk-origtargz, wrap-and-sort
  #   build-essential debhelper quilt    - building the 3.0 (quilt) source
  #   lintian dput                       - package checks and upload
  apt update && apt install -y \
    git git-buildpackage pristine-tar devscripts build-essential \
    debhelper quilt lintian dput
  mk-build-deps --install --remove --tool='apt-get -y --no-install-recommends' \
    debian/control

Signing usually needs the GPG key forwarded into the container; the common
practice is to build unsigned here (`-us -uc`) and run `debsign` on the host.

6. BUILD MECHANICS
==================
* `debian/rules` sets `USE_BUNDLED_LUA=0`, `PREFIX=/usr`, `KEEP_SYMBOLS=1`
  (the last keeps debug info so `dh_strip` can emit the `-dbgsym` package).
* Builds against system `liblua5.5-dev` instead of the bundled Lua engine.
* `docs/documentation.xml` -> HTML via `xsltproc`; the manpage is generated by
  `help2man` from `sjasmplus --help` output.

Vendored code kept after DFSG pruning (documented per-file in `debian/copyright`):

* `LuaBridge/` (minus `Tests/`, `third_party/`): header-only C++/Lua binding,
  no Debian package, tightly integrated into the build.
* `unittest-cpp/`: build/test-only, not installed, not packaged for Debian.
* `crc32c/`: a small embedded code snippet, not a complete upstream library.

These have no packaged Debian equivalents (and `unittest-cpp` is test-only);
unbundling would require upstream refactoring out of scope for packaging.

7. SEPARATE CHECKOUTS
=====================
Keep two clones: the upstreamvcs repository (real submodules) and the Salsa
packaging repository (imported `upstream/*` with submodules flattened to plain
files). Mixing both representations in one working tree leaves stale gitlink /
submodule metadata behind. If a Salsa checkout shows leftover submodule state
from earlier experiments:

  git submodule deinit -f --all
  git clean -ffd
  # if it persists, remove the matching .git/modules/* entries

8. ONE-TIME BOOTSTRAP
=====================
Only needed when creating the Salsa repository from scratch (already done for
sjasmplus); afterwards use the per-release workflow in section 3.

In the upstreamvcs clone, create `gen-dfsg-tarball` with the initial `debian/`
metadata and generate the first `+dfsg` tarball (section 3, step 1). Then, in an
empty Salsa clone:

  git checkout --orphan upstream/latest
  git rm -rf .
  git commit --allow-empty -m 'Initial upstream branch.'

  gbp import-orig --no-merge --no-symlink-orig \
    --upstream-branch=upstream/latest ../sjasmplus_1.23.1+dfsg.orig.tar.xz

  git checkout -b debian/latest
  git add debian
  git commit -m "debian: initial packaging baseline for 1.23.1+dfsg"

  git push origin upstream/latest
  git push origin pristine-tar
  git push origin debian/latest
  git push origin tag upstream/1.23.1+dfsg

9. NOTES FROM THE FIRST FAILED APPROACH
=======================================
The first attempt mirrored upstream history directly into `upstream/latest`,
layered `debian/latest` on top, and let `mk-origtargz` repack the orig tarball
on the fly (in Salsa CI). It was abandoned because the Debian orig tarball is
not a direct archive of the upstream tree: it drops DFSG files and expands
submodules, and Salsa CI reconstructs the source package even for binary jobs,
so the orig-reproduction path must be exact.

That produced persistent CI mismatches: wrong orig contents in `build source`,
line-ending differences in Windows `.rc` files across export paths, and
`pristine-tar` verification failures when the upstream tree did not match the
repacked tarball. The imported-upstream design exists to avoid repeating that
work; its added complexity is intentional and keeps the canonical Debian source
aligned with what Salsa CI and `gbp` can rebuild reliably.

 -- Peter Helcmanovsky <ped@7gods.org>
