TNT/docs/CICD.md

CI / RELEASE GUIDE
==================

AUTOMATIC TESTING
-----------------
Every push or PR automatically runs:
  - Build on Ubuntu
  - AddressSanitizer build
  - `make ci-test` (strict integration, anonymous access, connection limits,
    and security feature checks)
  - Release/package preflight (`make release-check`)

Check status:
  https://github.com/m1ngsama/TNT/actions

Production deployment is intentionally manual. The CI workflow must not SSH
into production or restart services on push.


CREATING RELEASES
-----------------
Release policy:
  - Use SemVer-style tags: vMAJOR.MINOR.PATCH.
  - Bump PATCH for compatible bug fixes and release hardening.
  - Bump MINOR for new commands, new documented flags, JSON field additions,
    or visible user-interface behavior changes.
  - Bump MAJOR for incompatible command, config, storage, or package behavior.
  - Keep GitHub draft release review manual. Do not auto-publish releases.
  - Keep production deployment manual. Do not SSH into production from CI.

1. Update version metadata:
   - include/common.h
   - tnt.1
   - docs/CHANGELOG.md
   - packaging/arch/PKGBUILD
   - packaging/homebrew/tnt-chat.rb
   - packaging/debian/debian/changelog
   - maintainer metadata, when preparing public package recipes

2. Run the local preflight:
   make release-check

   For a longer local runtime gate before publishing or production rollout:
   RUN_SOAK=1 RUN_SLOW_CLIENT=1 make release-check

3. Commit the release changes and create a local tag.  Do not push the tag
   until strict checks pass:
   git tag vX.Y.Z

4. Run strict release checks:
   make release-check-strict

   Strict mode requires the local `vX.Y.Z` tag to point at HEAD.  It also
   builds from the tagged source archive, so it catches files that were left
   untracked and would be missing from GitHub's source archive.

5. Push the tag:
   git push origin vX.Y.Z

6. GitHub Actions automatically:
   - Builds `tnt` and `tntctl` binaries (Linux/macOS, AMD64/ARM64)
   - Creates a draft release
   - Uploads binaries
   - Generates one `checksums.txt` file
   - Verifies that artifact architecture matches the asset name

7. Review the draft release, smoke-test downloaded assets, then publish it
   manually from GitHub.

8. Release appears at:
   https://github.com/m1ngsama/TNT/releases


RELEASE REVIEW CHECKLIST
------------------------
Before publishing a draft release:
  - Confirm `git tag` points at the intended commit.
  - Download every release asset from GitHub, not from the local workspace.
  - Verify downloaded assets against `checksums.txt` (`sha256sum -c
    checksums.txt --ignore-missing` on Linux, or `shasum -a 256 -c` for each
    downloaded asset on macOS).
  - Run downloaded `tnt --version` and `tntctl --version`.
  - Start a temporary server and check:
      ssh -p 2222 server health
      ssh -p 2222 server stats --json
      ssh -p 2222 server users --json
      ssh -p 2222 operator@server post "release smoke"
      ssh -p 2222 server "tail -n 1"
  - Check runtime dynamic links (`ldd` on Linux, `otool -L` on macOS) and make
    sure `libssh` is documented for the target install path.
  - Confirm `make release-check-strict` passed before pushing the tag.
  - For package-manager recipes, download the final GitHub source archive,
    replace Arch/Homebrew source checksums, then run:
      SOURCE_TARBALL=dist/tnt-chat-vX.Y.Z.tar.gz make package-publish-check


ROLLBACK
--------
Production rollback stays manual:
  1. Keep the previous binary before replacing it.
  2. Stop or restart only the intended `tnt` service.
  3. Restore the previous binary if smoke checks fail.
  4. Re-run `health`, `stats --json`, and one post/tail smoke test.

Do not overwrite `TNT_STATE_DIR` during rollback.  If a future release changes
the message log format, its release notes must include the downgrade behavior.


DEPLOYING TO SERVERS
--------------------
Deployments are operator-driven:
  1. Build and test locally or in a temporary server directory.
  2. Back up the installed binary.
  3. Install the new binary.
  4. Restart the service.
  5. Run black-box checks (`health`, `stats --json`, `users --json`,
     and a post/tail smoke test).

The installer can still be used manually on a server:
  curl -sSL https://raw.githubusercontent.com/m1ngsama/TNT/main/install.sh | sh


PRODUCTION SETUP (systemd)
---------------------------
1. Install binary (see above)

2. Setup service:
   sudo useradd -r -s /bin/false tnt
   sudo mkdir -p /var/lib/tnt
   sudo chown tnt:tnt /var/lib/tnt
   sudo cp tnt.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable --now tnt

3. Check status:
   sudo systemctl status tnt
   sudo journalctl -u tnt -f


UPDATING SERVERS
----------------
Manual binary replacement pattern:
  backup=/usr/local/bin/tnt.bak-$(date +%Y%m%d%H%M%S)
  sudo cp -a /usr/local/bin/tnt "$backup"
  sudo install -m 755 ./tnt /usr/local/bin/tnt
  sudo systemctl restart tnt


PLATFORMS SUPPORTED
-------------------
✓ Linux AMD64 (x86_64)
✓ Linux ARM64 (aarch64)
✓ macOS Intel (x86_64)
✓ macOS Apple Silicon (arm64)


EXAMPLE WORKFLOW
----------------
# Local development
make && make asan && make release-check
./tnt

# Create release
git tag vX.Y.Z
git push origin vX.Y.Z
# Wait 5 minutes for builds

# Deploy to production manually after validation
ssh server "sudo install -m 755 /tmp/tnt-build/tnt /usr/local/bin/tnt"
ssh server "sudo systemctl restart tnt"
ssh -p 2222 server health