xtc/docs/MAINTENANCE.md

# Release and Maintenance Policy

## Supported Development Target

Initial target: x86_64 Artix/Arch-family Linux with glibc, CMake 3.25+ and a backend such as Ninja, GCC/Clang,
FLTK 1.4 and a JACK-compatible client/server. The inspected host uses GCC
16.2.1, FLTK 1.4.5 and the dependencies in LICENSES.md.
Core-only/no-JACK/no-LADSPA builds are checked too. Build on the destination
distribution for different library ABIs; there is no cross-distribution
static-binary promise. Python 3.12+ and binutils are build/package/test tools
only. No dependency is fetched automatically.

---

## Release Checklist

1. Work from a clean reviewed commit. Record `git rev-parse HEAD`, compiler,
   libc/FLTK/JACK versions and `xtc-check --diagnose`. No automatic version
   bump, Git tag, public upload or external release is performed by local
   targets.
2. Run warning-enabled
   `cmake -S . -B build -DXTC_ENABLE_LIVE_TESTS=ON && cmake --build build --parallel && cmake --build build --target check gui test-plugins test-plugins-real test-gui-plugins test-workflow test-gui-jack test-jack-midi test-recording test-recovery test-reliability test-scale analyze`
   where dependencies exist.
3. Use a separate CMake binary directory for ASan/UBSan/leak runs and another for optional-
   dependency builds. GUI leak checks use only the documented fontconfig
   suppression; core tests use none. Run publication/recording race tests as
   described in RELIABILITY.md. Sanitizers are not latency qualification.
4. Run `cmake --build build --target benchmark test-performance test-stress`; compare on matching
   host/compiler/flags against a reviewed baseline. Investigate regressions; do
   not weaken thresholds or replace evidence without explanation.
5. Run `cmake --build build --target test-install test-release test-package`. Inspect archive manifests,
   hashes, dynamic dependency names and licenses. Source exports rebuild twice
   with identical artifacts on this host. Repeat binary packaging compares
   bytes.
6. Complete physical listening, recording/device/endurance, and independent
   human install/workflow checks before claiming production qualification. They
   remain pending for this prototype, even when all automated checks pass.
7. Save checksums/test logs/conditions with the proposed release. Review known
   limitations and format compatibility and update user/developer docs.
   Publishing or distro repository submission is a separate action.

---

## Regressions and Compatibility

Report the exact version/commit, OS/toolchain, compiled features, reproduction,
expected/actual output, GUI errors/xruns and whether plugins are involved. Keep
a minimal project/media fixture when redistribution is permitted; do not attach
private recordings or full memory dumps inadvertently. No telemetry/upload
occurs.

A confirmed defect gets a focused deterministic regression or repeatable runtime
check before its fix. Memory/thread/file-loss defects take priority; disable the
unsafe path rather than silently dropping media or unknown project records. Keep
candidate preparation/plan publication transactional and callbacks bounded.

Format changes increment XTC_PROJECT_FORMAT_VERSION, retain explicit bounded
migrations/fixtures for all supported older versions, and add
malformed/roundtrip checks. Unknown versions/types/records fail with actionable
errors. Never rewrite an unsupported source file during failed Open. Keep the
original when diagnosing post-publication sync errors. Native descriptor ABI
compatibility is distinct from project format and is documented in
NATIVE_API.md; opaque DSP state is not promised. No public stability guarantee
or support SLA is implied by development version 0.1.0.

---

## Support and Triage Record

Verified compilers are GCC/G++ 16.2.1 and Clang/Clang++ 23.1.3 on x86_64 Linux;
these are tested versions, not a promise that arbitrary older/newer versions
work. The code requires C99 plus GCC/Clang lock-free atomics, C++17 for the GUI,
FLTK 1.4 and POSIX/glibc APIs. JACK (including PipeWire's JACK compatibility) is
the only live backend. Native Windows/macOS, other architectures and direct ALSA
backends are not qualified. Core builds can disable JACK, FLTK and LADSPA. See
BUILD.md and LICENSES.md for dependency roles and versions.

Release qualification adds `test-install-layout`, installed example inspection,
all performance report resources, source checksum verification and the current
RELEASE_NOTES.md. Retain the original graph benchmark alert in release records;
a successful compile does not clear timing qualification gaps.

File reproducible bugs with the repository maintainers using the source commit
and archive SHA-256, `xtc-check --version`/`--diagnose`, distro/kernel and
toolchain, exact commands or GUI steps, expected versus observed behavior and
frequency. Reduce to a redistributable project and state whether it reproduces
without external plugins and with the offline/core tools. Include relevant
stderr and sanitizer traces; preserve original recovery files before
experimenting.

Maintainers should first confirm version/features and reproduce in an isolated
build. Prioritize data loss/security/memory/thread defects, then crashes and
callback/deadline failures, then functional bugs and UI issues. Record severity,
reproduction conditions, affected versions, regression test and verification
command with the fix. Route timing-only alerts through matching-host reports and
repeat measurements; do not treat sanitized timings as realtime evidence.